https://webwork.maa.org/mediawiki_new/api.php?action=feedcontributions&user=141.154.51.251&feedformat=atomWeBWorK_wiki - User contributions [en]2024-03-29T12:37:52ZUser contributionsMediaWiki 1.34.0https://webwork.maa.org/mediawiki_new/index.php?title=Installation_Manual_for_2.16_on_Ubuntu&diff=20951Installation Manual for 2.16 on Ubuntu2021-05-20T10:49:18Z<p>141.154.51.251: /* Changing the default MySQL/MariaDB engine */</p>
<hr />
<div><br />
{{UnderConstruction}}<br />
<br />
'''These instructions are a work in progress. '''<br />
<br />
<br />
These instructions cover the installation of WeBWorK 2.16 for Ubuntu Server 20.04 LTS. <br />
<br />
If you are just upgrading WeBWorK, especially if you already have existing WeBWorK courses, see [[Upgrading_WeBWorK_with_Github]].<br />
<br />
Also, it is assumed that you have Ubuntu Server 20.04 LTS installed. You can visit [[Installation_Manual_for_2.15_on_Ubuntu_20.04_Server]] for instructions on installing Ubuntu 20.04 LTS. Also make sure the OS is upgraded to all patches within the version you are running. <br />
<br />
== Notation ==<br />
<br />
First some short comments on notation we will be using. We will use <code>&lt;key&gt;</code> to indicate that you should press a specific key (e.g. <code>&lt;Enter&gt;</code>, <code>&lt;Tab&gt;</code>, <code>&lt;F12&gt;</code>, etc.). Sometimes we will also use e.g. <code>&lt;wwadmin password&gt;</code> to indicate you have to enter the wwadmin password.<br />
<br />
<code>^</code> will indicate the <code>&lt;Ctrl&gt;</code> key so e.g. <code>^X</code> is really shorthand for <code>&lt;Ctrl&gt; &lt;X&gt;</code>, i.e. press the Ctrl key and hit the X key.<br />
<br />
Code blocks that begin with <code>#</code> must be run with root privileges (via either a root shell or prefixing the command with <code>sudo</code>). You can enter a root shell with <code>sudo -s</code>. Code blocks that begin with <code>$</code> may be run as a standard user. You are not intended to type the <code>#</code> or <code>$</code> characters as part of the provided commands.<br />
<br />
==Install Software Packages==<br />
<br />
=== Ubuntu Software Packages ===<br />
<br />
On Ubuntu and other Debian linuxes, the following instructions will get needed software packages installed. <br />
<br />
Here is the list of Ubuntu packages that need to be installed. <br />
<br />
# <code>apache2</code><br />
# <code>cpanminus</code><br />
# <code>curl</code><br />
# <code>dvipng</code><br />
# <code>dvisvgm</code><br />
# <code>gcc</code><br />
# <code>git</code><br />
# <code>imagemagick</code><br />
# <code>libapache2-request-perl</code><br />
# <code>libarchive-zip-perl</code><br />
# <code>libarray-utils-perl</code><br />
# <code>libcrypt-ssleay-perl</code><br />
# <code>libdancer-perl</code><br />
# <code>libdancer-plugin-database-perl</code><br />
# <code>libdata-dump-perl</code><br />
# <code>libdatetime-perl</code><br />
# <code>libemail-address-xs-perl</code><br />
# <code>libemail-sender-perl</code><br />
# <code>libexception-class-perl</code><br />
# <code>libextutils-xsbuilder-perl</code><br />
# <code>libfile-find-rule-perl-perl</code><br />
# <code>libgd-perl</code><br />
# <code>libhtml-scrubber-perl</code><br />
# <code>libhttp-async-perl</code><br />
# <code>libiterator-perl</code><br />
# <code>libiterator-util-perl</code><br />
# <code>libjson-perl</code><br />
# <code>liblocale-maketext-lexicon-perl</code><br />
# <code>libmime-tools-perl</code><br />
# <code>libmoox-options-perl</code><br />
# <code>libnet-ip-perl</code><br />
# <code>libnet-ldap-perl</code><br />
# <code>libnet-oauth-perl</code><br />
# <code>libossp-uuid-perl</code><br />
# <code>libpadwalker-perl</code><br />
# <code>libpath-class-perl</code><br />
# <code>libphp-serialization-perl</code><br />
# <code>libpod-wsdl-perl</code><br />
# <code>libsoap-lite-perl</code><br />
# <code>libsql-abstract-perl</code><br />
# <code>libstring-shellquote-perl</code><br />
# <code>libtemplate-perl</code><br />
# <code>libtext-csv-perl</code><br />
# <code>libtimedate-perl</code><br />
# <code>libuuid-tiny-perl</code><br />
# <code>libxml-parser-easytree-perl</code><br />
# <code>libxml-parser-perl</code><br />
# <code>libxml-writer-perl</code><br />
# <code>make</code><br />
# <code>netpbm</code><br />
# <code>npm</code><br />
# <code>openssh-server</code><br />
# <code>pdf2svg</code><br />
# <code>preview-latex-style</code><br />
# <code>texlive</code><br />
# <code>texlive-latex-extra</code><br />
# <code>unzip</code><br />
<br />
<br />
'''To install all of these packages in one fell swoop''' run the command ('''obviously you want to use cut and paste''')<br />
<br />
$ sudo apt install apache2 cpanminus curl dvipng dvisvgm gcc git imagemagick libapache2-request-perl \<br />
libarchive-zip-perl libarray-utils-perl libcrypt-ssleay-perl libdancer-perl \<br />
libdancer-plugin-database-perl libdata-dump-perl libdatetime-perl libemail-address-xs-perl \<br />
libemail-sender-perl libexception-class-perl libextutils-xsbuilder-perl \<br />
libfile-find-rule-perl-perl libgd-perl libhtml-scrubber-perl libhttp-async-perl \<br />
libiterator-perl libiterator-util-perl libjson-perl liblocale-maketext-lexicon-perl \<br />
libmime-tools-perl libmoox-options-perl libnet-ip-perl libnet-ldap-perl libnet-oauth-perl \<br />
libossp-uuid-perl libpadwalker-perl libpath-class-perl libphp-serialization-perl \<br />
libpod-wsdl-perl libsoap-lite-perl libsql-abstract-perl libstring-shellquote-perl \<br />
libtemplate-perl libtext-csv-perl libtimedate-perl libuuid-tiny-perl \<br />
libxml-parser-easytree-perl libxml-parser-perl libxml-writer-perl make netpbm npm \<br />
openssh-server pdf2svg preview-latex-style texlive texlive-latex-extra unzip<br />
<br />
Enter the password for wwadmin at the prompt:<br />
<br />
[sudo] password for wwadmin: <wwadmin password><br />
<br />
Accept any prompts with the default answer by hitting <code>&lt;Enter&gt;</code>.<br />
<br />
=== Installation of Other Perl Modules with cpanm ===<br />
<br />
We will use <code>cpanm</code> to install other perl modules. For example, one module, <code>Statistics::R::IO</code> that will be needed is not in a standard package. To install this<br />
<br />
$ sudo cpanm Statistics::R::IO<br />
[sudo] password for wwadmin: <wwadmin password><br />
<br />
Below, we will determine other perl modules that will need to be installed with this method.<br />
<br />
== Setting up Apache2 ==<br />
<br />
This sets up some helpful modules for apache and tests to make sure that apache is up and running.<br />
<br />
=== enabling info.conf and status.conf in Ubuntu ===<br />
<br />
We enable the info module. Acting as <code>root</code> in a terminal window enter<br />
$ sudo -s<br />
[sudo] password for wwadmin: <wwadmin password><br />
# a2enmod info<br />
<br />
Next we make a copy of the configuration files we will be editing for safekeeping. <br />
<br />
# cd /etc/apache2/mods-available<br />
<br />
# cp info.conf info.conf.bak1<br />
# cp status.conf status.conf.bak1<br />
<br />
# exit<br />
$<br />
<br />
Now we will edit configuration files <code>info.conf</code> and <code>status.conf</code> to allow us to view information about the setup and performance of the web server. Note that this is not absolutely necessary but it can be very useful. You can use your favorite editor but we will give instructions assuming you are using <code>nano</code>. Note that you have to be root to edit these files. First we edit <code>info.conf</code><br />
<br />
$ cd /etc/apache2/mods-available<br />
$ sudo nano info.conf<br />
[sudo] password for wwadmin: <wwadmin password><br />
<br />
I suggest you allow access to server information from e.g. your department domain. To do this uncomment (i.e. remove the <code>#</code> from) <br />
Require ip 192.0.2.0/24<br />
and then replace <code>192.0.2.0/24</code> by <code>.math.yourschool.edu</code><br />
where of course you should edit <code>.math.yourschool.edu</code> appropriately. <br />
<br />
Then save the file and quit (press <code>^X</code>, <code>Y</code>, <code>&lt;Enter&gt;</code>).<br />
<br />
Now we edit <code>status.conf</code><br />
<br />
$ cd /etc/apache2/mods-available<br />
$ sudo nano status.conf<br />
[sudo] password for wwadmin: <wwadmin password><br />
<br />
Edit the <br />
#Require ip 192.0.2.0/24<br />
line just as you did for <code>info.conf</code>.<br />
Then save the file and quit. And restart Apache so that the above changes take effect<br />
<br />
$ sudo systemctl restart apache2<br />
password:<wwadmin password><br />
<br />
===Fully Qualified Domain Name=== <br />
Now we have to set your server's fully qualified domain name. Note that if your network was set up automatically via DHCP, your server's fully qualified domain name should already be set up. You can check by running the <code>hostname</code> commands below.<br />
<br />
Run the command <br />
sudo hostnamectl set-hostname webwork<br />
[sudo] password for wwadmin: <wwadmin password><br />
where of course you should replace webwork by whatever your server's name is.<br />
<br />
<br />
You can check these settings by running the commands<br />
<br />
$ hostname --fqdn<br />
and <br />
$ hostname<br />
<br />
The first gives the server's fully qualified domain name (e.g. webwork.mydepartment.myschool.edu) and the second the server's name (e.g. webwork).<br />
<br />
Note that if your server can not find its fully qualified domain name, certain tools (such as the Synaptic Package Manager) may not start.<br />
<br />
===Test Apache===<br />
Now restart Apache<br />
<br />
$ sudo systemctl restart apache2<br />
password:<wwadmin password><br />
or<br />
$ sudo apache2ctl restart<br />
[sudo] password for wwadmin: <wwadmin password><br />
or<br />
$ sudo service apache2 restart<br />
[sudo] password for wwadmin: <wwadmin password><br />
<br />
<br />
and test your server by connecting to your<br />
server ("http://yourserver.yourschool.edu") from a browser on a remote machine. You should see the '''Apache2 Ubuntu Default Page''' indicating that Apache is running.<br />
<br />
You can check Apache's status by connecting to<br />
"http://yourserver.yourschool.edu/server-status" from a browser on a remote machine in the math.yourschool.edu domain.<br />
<br />
Further test Apache by connecting to<br />
"http://yourserver.yourschool.edu/server-info" from a browser on a remote machine in the math.yourschool.edu domain and you will see a page listing various <br />
information about Apache. In particular under <code>Server Settings</code> you should see<br />
<br />
Server Version: Apache/2.4.41 (Ubuntu) mod_apreq2-20090110/2.8.0 mod_perl/2.0.11 Perl/v5.30.0<br />
(or something very similar) indicating that both <code>mod_apreq2</code> and <code>mod_perl</code> are installed.<br />
<br />
If you have problems now or in the future, a good first thing to do is to look at the Apache error log which is located at <code>/var/log/apache2/error.log</code>. In the directory <code>/var/log/apache2/</code> you can "less" through the error log (<code>less error.log</code>), look at the last few entries (<code>tail error.log</code>) or run the command <code>tail -f error.log</code> which will display new error messages as they are appended to the file. Use <br />
<code>^C</code> to break out of <code>tail -f</code> . For example if you didn't set up access to "server-info", you can run<br />
tail /var/log/apache2/error.log<br />
and in the output you should see something similar to<br />
...[mpm_event:notice] [pid 48932:tid 140494759132224] AH00489: Apache/2.4.41 (Ubuntu) mod_apreq2-20090110/2.8.0 mod_perl/2.0.11 Perl/v5.30.0 configured -- resuming normal operations<br />
indicating that both <code>mod_apreq2</code> and <code>mod_perl</code> are installed and running.<br />
<br />
== Installing a Database ==<br />
<br />
This section installs either MySQL or MariaDB as the database manger for webwork. It is recommended that MariaDB is used. There have been a few examples of connection issues with MySQL. <br />
<br />
<br />
=== Installing and Testing MariaDB ===<br />
<br />
Install MariaDB using the distro packages. <br />
<br />
$ sudo apt install mariadb-server libdbd-mariadb-perl<br />
<br />
<br />
=== Installing and Testing MySQL ===<br />
<br />
If you wish to use MySQL: <br />
<br />
$ sudo apt install mysql-server libdbd-mysql-perl<br />
<br />
=== Securing the Database ===<br />
<br />
Then we should secure the server<br />
<br />
$ sudo mysql_secure_installation<br />
[sudo] password for wwadmin: <wwadmin password><br />
<br />
You can setup the VALIDATE PASSWORD plugin if you wish. I chose not to.<br />
<br />
Next you will be asked to enter a<br />
<code>New password for the MySQL "root" user</code>. Enter your chosen MySQL <code>root</code> password. You have to enter a password but it will not be used. In Ubuntu systems running MySQL 5.7 (and later versions), the root MySQL user is set to authenticate using the auth_socket plugin by default rather than with a password. <br />
<br />
You almost certainly want to answer 'Y' to all questions '''except''' possibly for the first one which asks if you want to set up a VALIDATE PASSWORD plugin.<br />
Now test that all is well:<br />
<br />
$ sudo mysql <br />
[sudo] password for wwadmin: <wwadmin password><br />
<br />
You should see<br />
<br />
Welcome to the MySQL monitor ...<br />
mysql><br />
<br />
Now lets check the MySQL users.<br />
There are five accounts. To see the accounts, do the following <br />
<br />
mysql> SELECT user,authentication_string,plugin,host FROM mysql.user;<br />
<br />
You will see a table with five users (<code>debian-sys-maint</code>, <code>mysql.infoschema</code>, <code>mysql.session</code>, <code>mysql.sys</code> and <code>root</code>). <br />
You should see that one of the five users has a valid password (which will be displayed in encrypted form) and <code>root</code> is authenticated by a socket. You can ignore the <code>mysql.session</code>, <code>mysql.sys</code> and <code>mysql.infoschema</code> users.<br />
<br />
Now exit MySQL<br />
<br />
mysql> exit<br />
Bye<br />
$<br />
<br />
This last step is optional since currently most of WeBWorK's MySQL tables are now created using the MyISAM engine (by default -- this can be changed in the config files) rather than the MySQL default engine. Now we change MySQL's default engine. The default engine is InnoDB as of MySQL 5.5.5 (MyISAM before 5.5.5) but (at least on some hardware) InnoDB seems to be 50-100 times slower than MyISAM. So we will change the default MySQL engine from InnoDB to MyISAM. Note that this change only applies to new tables, tables already constructed will continue to use InnoDB. But we haven't created any WeBWorK tables so we don't have to change the engine for any existing tables.<br />
<br />
=== Changing the default MySQL/MariaDB engine ===<br />
<br />
To change the default MySQL engine from InnoDB to MyISAM do the following:<br />
<br />
$ cd /etc/mysql/mysql.conf.d<br />
$ sudo cp mysqld.cnf mysqld.cnf.bak1<br />
[sudo] password for wwadmin: <wwadmin password><br />
$ sudo nano mysqld.cnf<br />
<br />
If MariaDB is used instead of MySQL then edit the file <code>/etc/mysql/mariadb.conf.d/50-server.cnf</code>, instead of <code>/etc/mysql/mysql.conf.d/mysqld.cnf</code>.<br />
<br />
Search for <code>[mysqld]</code> and under "Basic Settings" above the "user = mysql" line add the line<br />
default-storage-engine = myisam<br />
<br />
Then save the file and quit. Restart MySQL.<br />
<br />
$ sudo systemctl restart mysql<br />
[sudo] password for wwadmin: <wwadmin password><br />
<br />
and log into mysql<br />
$ sudo mysql <br />
[sudo] password for wwadmin: <wwadmin password><br />
<br />
You will see<br />
<br />
Welcome to the MySQL monitor ...<br />
mysql><br />
<br />
If you show MySQL engines<br />
<br />
mysql> SHOW ENGINES\G<br />
<br />
you should see that MyISAM is listed as the default engine:<br />
...<br />
*************************** 5. row ***************************<br />
Engine: MyISAM<br />
Support: DEFAULT<br />
Comment: MyISAM storage engine <br />
Transactions: NO<br />
XA: NO<br />
Savepoints: NO<br />
<br />
Now exit<br />
mysql> exit<br />
Bye<br />
$<br />
<br />
== Downloading the WeBWorK System Software and Problem Libraries ==<br />
We are finally at the point where we can start downloading and installing WeBWorK. We will use Git to download WeBWorK from Github. This is easy and it will also make it easy to update the system in the future. Note that the following are rather long commands; it is much easier to copy (<code>^C</code>) them from this document and paste (<code>&lt;Shift&gt; &lt;Ctrl&gt; &lt;V&gt;</code><br />
or <code>&lt;Shift&gt; &lt;Insert&gt;</code>) them in a terminal window<br />
<br />
$ cd<br />
$ cd downloads<br />
$ git clone git://github.com/openwebwork/webwork2.git<br />
$ git clone git://github.com/openwebwork/pg.git<br />
$ git clone git://github.com/openwebwork/webwork-open-problem-library.git<br />
<br />
'''Important Note'''. The above commands retrieve the master branch which gives the latest stable release of the software package (webwork2, pg, etc.) with bug fixes. If a stable release newer than 2.15 exists, that will be downloaded and these instructions may be a little out of date. So it is a good idea to check before downloading. The best way to do that is to look at https://github.com/openwebwork/webwork2/blob/master/VERSION and https://github.com/openwebwork/pg/blob/master/VERSION.<br />
<br />
The first and second download gives you the latest released versions.<br />
The third download contains the WeBWorK Open Problem Library (OPL) which is the new name for the original National Problem Library (NPL). The NPL has been renamed to reflect its growing international content. Your system will be loaded with many thousands of WeBWorK problems (over 30,000 currently).<br />
<br />
The main information page about WebWork downloads is available at http://webwork.maa.org/wiki/Category:Release_Notes<br />
<br />
The main information page about the OPL is available at http://webwork.maa.org/wiki/Open_Problem_Library<br />
<br />
==Installing WeBWorK==<br />
<br />
'''Note the instructions below assume you are installing WeBWorK from scratch. If you are just upgrading WeBWorK, especially if you already have existing WeBWorK courses, see [[Upgrading WeBWorK]].'''<br />
<br />
=== Move the System into the Required Directories ===<br />
As <code>root</code> create a <code>webwork</code> directory under <code>/opt</code>, change the ownership of the <code>webwork</code> directory to <code>www-data</code>, which is what the apache server runs as and move directories there. <br />
<br />
$ cd<br />
$ cd downloads<br />
$ sudo mkdir /opt/webwork<br />
[sudo] password for wwadmin: <wwadmin password><br />
$ sudo chown www-data:www-data /opt/webwork<br />
$ sudo mv webwork2 /opt/webwork/<br />
$ sudo mv pg /opt/webwork/<br />
<br />
<br />
<br />
Now create the <code>courses</code> and <code>libraries</code> directories under <code>webwork</code> and copy and move content there <br />
<br />
$ sudo mkdir /opt/webwork/courses<br />
$ sudo mkdir /opt/webwork/libraries<br />
$ sudo mv webwork-open-problem-library /opt/webwork/libraries/<br />
$ cd /opt/webwork/webwork2/courses.dist<br />
$ sudo cp *.lst /opt/webwork/courses/<br />
$ sudo rsync -a modelCourse /opt/webwork/courses/<br />
<br />
=== Setting Permissions ===<br />
<br />
The PG installation directory and files should be owned by <code>www-data</code> and not writable by other users:<br />
<br />
$ cd /opt/webwork/pg<br />
$ sudo chmod -R u+rwX,go+rX .<br />
<br />
Most WeBWorK directories and files should also be owned by <code>www-data</code> and not writable by other users:<br />
<br />
$ cd /opt/webwork/webwork2<br />
$ sudo chmod -R u+rwX,go+rX .<br />
<br />
Certain data directories need to be writable by the web server. These are <code>DATA</code>, <code>courses</code>, <code>htdocs/tmp</code>, <code>logs</code>, and <code>tmp</code>. It is convenient to give WeBWorK administrators access to these directories as well, so they can perform administrative tasks such as removing temporary files, creating and editing courses from the command line, managing logs, and so on. We will use the group <code>www-data</code>, containing both the WeBWorK administrators and the web server. Consider the user WWADMIN<br />
<br />
Run the command:<br />
$ sudo adduser wwadmin www-data<br />
<br />
$ id wwadmin<br />
<br />
and then you should see <code>wwdata</code> listed under groups. Also<br />
<br />
$ id www-data<br />
<br />
should show <code>www-data</code> listed under groups. <br />
<br />
Now we make the WeBWorK directories that need to be writable by the web server have <code>www-data</code> as their group. The following are rather long commands; you might want to copy them and paste them into your terminal window rather than typing them.<br />
<br />
$ sudo -s<br />
[sudo] password for wwadmin: <wwadmin password><br />
# cd /opt/webwork/webwork2/<br />
# chgrp -R www-data DATA ../courses htdocs/tmp htdocs/applets logs tmp /opt/webwork/pg/lib/chromatic<br />
# chmod -R g+w DATA ../courses htdocs/tmp htdocs/applets logs tmp /opt/webwork/pg/lib/chromatic<br />
# find DATA/ ../courses/ htdocs/tmp logs/ tmp/ -type d -a -exec chmod g+s {} \;<br />
# exit<br />
$<br />
<br />
=== Compile color.c ===<br />
<br />
$ cd /opt/webwork/pg/lib/chromatic<br />
$ gcc color.c -o color<br />
<br />
You may see some warning messages which you can safely ignore.<br />
<br />
== Configuring the Shell ==<br />
<br />
To make working with WeBWorK easier, there are a couple of changes you can make to your shell environment.<br />
<br />
Add the WeBWorK <code>bin</code> directory to your path. This will allow you to run WeBWorK command-line utilities without typing the full path to the utility. Goto your home directory and backup your <code>.bashrc</code> file<br />
<br />
$ cd<br />
$ cp .bashrc .bashrc.bak1<br />
<br />
Now edit <code>.bashrc</code><br />
<br />
$ nano .bashrc<br />
<br />
After the last line add the three lines:<br />
<br />
export PATH=$PATH:/opt/webwork/webwork2/bin<br />
export WEBWORK_ROOT=/opt/webwork/webwork2<br />
export PG_ROOT=/opt/webwork/pg<br />
<br />
Then save the file and Quit.<br />
<br />
Close your Terminal Window and open a new one so the above changes<br />
take effect. You can check that they have by<br />
<br />
$ echo $PATH<br />
$ echo $WEBWORK_ROOT<br />
$ echo $PG_ROOT<br />
<br />
== Checking Module Dependencies ==<br />
<br />
WeBWorK includes a script called <code>check_modules.pl</code> (in the directory <code>/opt/webwork/webwork2/bin</code>) that verifies that the needed programs and Perl modules are installed on your system. Run this script to make sure you have installed the required programs and Perl modules.<br />
<br />
$ check_modules.pl apache2<br />
<br />
Scroll up and look through the listing. It should find everything. If something is missing (flagged by <code>**</code>), look back through these instructions to find where it should have been installed and install it. <br />
<br />
You may see some warning messages like <br />
Prototype mismatch: sub main::from_json: none vs ($@) at (eval 188) line 2.<br />
Prototype mismatch: sub main::to_json: none vs ($@) at (eval 188) line 2.<br />
This is a known bug in libjson-perl and can be safely ignored.<br />
<br />
A common perl package that isn't installed is <code>Statistics::R::IO</code>. It can be installed with<br />
<br />
$ sudo cpanm Statistics::R::IO<br />
<br />
which will install any needed dependencies and run tests. <br />
<br />
=== Obtaining Javascript Libraries ===<br />
<br />
Javascript libraries are now obtained using <code>npm</code>. This includes the following javascript packages:<br />
<br />
# <code>codemirror</code><br />
# <code>fontawesome</code><br />
# <code>iframe-resizer</code><br />
# <code>jQuery</code><br />
# <code>jQuery-ui</code><br />
# <code>MathJax</code><br />
# <code>nestedSortable</code><br />
<br />
To install all of these: <br />
<br />
$ cd /opt/webwork/webwork2/htdocs/<br />
$ npm install<br />
<br />
=== Checking LaTeX packages ===<br />
<br />
Now we check that all necessary LaTeX packages have been installed. Run the commands<br />
$ cd<br />
$ pdflatex /opt/webwork/webwork2/bin/check_latex.tex<br />
and look for missing packages (you can ignore "No file check_latex.aux.").<br />
<br />
=== Miscillaneous System Patches ===<br />
<br />
There is a bug in the Perl XMLRPC::Lite package that occurs with UTF8 characters. This can be fixed by applying the following patch:<br />
<br />
$ sudo patch -p1 -d / < /opt/webwork/webwork2/docker-config/xmlrpc-lite-utf8-fix.patch<br />
<br />
If the users of your system will be using problems that utilize the new <code>PGtikz.pl</code> macro then you will need to apply the following patch:<br />
<br />
$ sudo patch -p1 -d / < /opt/webwork/webwork2/docker-config/imagemagick-allow-pdf-read.patch<br />
<br />
== Configuring WeBWorK ==<br />
<br />
=== Making Copies of the Distribution Configuration Files ===<br />
<br />
Before configuring the system, you must make local copies of the <code>site.conf</code> and <code>localOverrides.conf</code> configuration files, located in <code>/opt/webwork/webwork2/conf/</code> . <br />
<br />
$ cd /opt/webwork/webwork2/conf<br />
$ sudo cp site.conf.dist site.conf<br />
$ sudo cp localOverrides.conf.dist localOverrides.conf<br />
<br />
=== WeBWorK System 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 instructors 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 />
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 />
==== Edit the site.conf file ====<br />
Now edit <code>site.conf</code><br />
<br />
$ sudo nano /opt/webwork/webwork2/conf/site.conf<br />
<br />
First we have to add information about the Apache2 server setup. <br />
Search for <code>server_root_url</code> and edit the line so that it reads:<br />
<br />
$server_root_url = 'http://yourserver.yourschool.edu';<br />
<br />
where of course you should edit <code>yourserver.yourschool.edu</code> appropriately. The "http://" is important. '''If you are running a secure server (i.e., using SSL - really TLS), the url should start with https:<br />
but you should wait to make that change until after WeBWorK is up and running and you set up SSL. In that case the "https://" is important.<br />
<br />
==== Database Settings ====<br />
<br />
Search for the code <code>$database_driver</code>. Uncomment the type of database you set up (MySQL or MariaDB) and comment out the other. <br />
<br />
We need to set a password that WeBWorK uses when it communicates with the MySQL database. Note that this is not the same as the <code>&lt;mysql root password&gt;</code> which is the unused password we set when securing MySQL.<br />
Search for <code>database_password</code> and replace the line<br />
$database_password = "passwordRW";<br />
by <br />
$database_password = 'database_password';<br />
where of course you should replace "database_password" with your own password but do use the single quotes. Remember this password as we will need it below.<br />
<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 />
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 />
'''Note:''' Some servers will need to set a value of <code>$server_apache_version</code> in <code>site.conf</code>. This setting is needed when the Apache settings disable the display of the Apache version number in Apache banner of the HTTP headers, typically by setting <code>ServerTokens Prod</code> in the Apache cponfig, as many security teams will recommend. In such cases, without a setting for this variable, WeBWorK will fail to detect that you are using Apache 2.4 and users will run into error pages reporting <code>Can't locate object method "remote_addr" via package "Apache2::Connection" at /opt/webwork/webwork2/lib/WeBWorK/Authen.pm</code> which will also appear in the Apache error.log file. The fix is to search for <code>$server_apache_version</code>, uncomment the line, and set a suitable value (currently "2.4" should work, and a fix to support settings like "2.4.29" is pending).<br />
<br />
Then save the file and Quit.<br />
<br />
==== Default Header Files ====<br />
<br />
After you have used WeBWorK for awhile, you may want to change the default header files in <code>defaults.config</code>. Search for <code>$webworkFiles{screenSnippets}{setHeader}</code> and <code>$webworkFiles{hardcopySnippets}{setHeader}</code> in <code>localOverrides.config</code>. Settings in the conf and config files affect all WeBWorK courses. You can override any setting in these conf and config files for an individual course by putting the local setting in <code>course.conf</code>.<br />
<br />
=== Set up the webwork database ===<br />
<br />
WeBWorK uses a single database, called <code>webwork</code>, for all courses. We will create the <code>webwork</code> database now.<br />
<br />
To do this do the following ('''before you just copy, paste and hit <code>&lt;Enter&gt;</code>''' notice that you have to replace <code>database_password</code> with the password you set when editing <code>site.conf</code> above):<br />
<br />
$ sudo mysql <br />
[sudo] password for wwadmin: <wwadmin password><br />
<br />
mysql> CREATE DATABASE webwork;<br />
mysql> CREATE USER 'webworkWrite'@'localhost' IDENTIFIED BY 'database_password';<br />
mysql> GRANT SELECT, INSERT, UPDATE, DELETE, CREATE, ALTER, DROP, LOCK TABLES ON webwork.* TO 'webworkWrite'@'localhost';<br />
mysql> exit<br />
Bye<br />
$ <br />
<br />
where as we said '''replace''' <code>database_password</code> with the password you set when editing <code>site.conf</code> above.<br />
<br />
=== Configuring Apache ===<br />
WeBWorK ships with an Apache config file that needs to linked into your Apache configuration process. The file is named <code>webwork.apache2.4-config.dist</code> and located in the <code>conf</code> directory. First, copy the file to <code>webwork.apache2-config</code>:<br />
<br />
$ cd /opt/webwork/webwork2/conf<br />
$ sudo cp webwork.apache2.4-config.dist webwork.apache2.4-config<br />
<br />
and now link it into your Apache configuration process<br />
<br />
$ sudo ln -s /opt/webwork/webwork2/conf/webwork.apache2.4-config /etc/apache2/conf-enabled/webwork.conf<br />
<br />
The default multi-processing module (MPM) for Apache is the event module but WeBWorK uses the prefork module. So we disable the event module and enable the prefork module.<br />
<br />
$ sudo a2dismod mpm_event<br />
$ sudo a2enmod mpm_prefork<br />
<br />
Next we will make a few changes to Apache's default configuration. We need to edit two files. First we will<br />
save copies of the original files. <br />
$ sudo -s<br />
# cd /etc/apache2/<br />
# cp apache2.conf apache2.conf.bak1<br />
# cd /etc/apache2/mods-available/<br />
# cp mpm_prefork.conf mpm_prefork.conf.bak1<br />
# exit<br />
<br />
====Edit apache2.conf====<br />
<br />
$ sudo nano /etc/apache2/apache2.conf<br />
<br />
Search for the line<br />
Timeout 300<br />
and replace it by<br />
Timeout 1200 <br />
<br />
Then save the file and quit. <br />
<br />
====Edit mpm_prefork.conf====<br />
<br />
$ cd /etc/apache2/mods-available/<br />
$ sudo nano mpm_prefork.conf<br />
<br />
Search for the lines<br />
MaxRequestWorkers 150<br />
MaxConnectionsPerChild 0<br />
Which occur under <code><IfModule mpm_prefork_module></code> and replace them by<br />
# For WeBWorK a rough rule of thumb is 5 MaxRequestWorkers per 1 GB of memory<br />
MaxRequestWorkers 10<br />
MaxConnectionsPerChild 50<br />
where you should set <code>MaxRequestWorkers</code> depending on the amount of memory your server has using the above rule of thumb. Note that for <br />
very busy servers, you should observe you memory usage and adjust the above settings as necessary. Also make sure MaxSpareServers is not set too high.<br />
<br />
Then save the file and quit.<br />
<br />
Finally we copy WeBWorK's icon file <code>favicon.ico</code> to Apache's <code>www</code> directory.<br />
$ sudo cp /opt/webwork/webwork2/htdocs/favicon.ico /var/www/html<br />
[sudo] password for wwadmin: <wwadmin password><br />
<br />
Now stop and start Apache. We do it this way to make sure the MPM gets changed. <br />
<br />
$ sudo apache2ctl stop<br />
[sudo] password for wwadmin: <wwadmin password><br />
$ sudo apache2ctl start<br />
<br />
== Test your configuration ==<br />
<br />
# Test the <code>/webwork2</code> location by visiting <code>http://yourserver.yourschool.edu/webwork2</code>. You should see the WeBWorK home page with no courses listed. Actually the directory <code>/opt/webwork/courses/</code> does contain the <code>modelCourse</code> but the <code>modelCourse</code> is not a real course so you will get an error message if you try to log into it. It will be used a as model for setting up other courses. For this reason <code>/opt/webwork/courses/modelCourse/</code> contains a file named <code>hide_directory</code> and so the <code>modelCourse</code> is not visible.<br />
# Test the <code>/webwork2_files</code> location by visiting <code>http://yourserver.yourschool.edu/webwork2_files</code>. You should see the "WeBWorK Placeholder Page".<br />
# You cannot test the <code>/webwork2_course_files</code> location until you have created a course.<br />
<br />
==If Something is Wrong ==<br />
If something is wrong one of the first things to check is that the config files have been edited correctly (e.g. one time a wrapped line in <code>localOverrides.conf</code> caused me problems, another time it was a missing single quote). A quick way to check this is to do a <code>diff</code> between the edited and distributed versions and check that <code>diff</code> reports the changes you made and only those. Another thing is to look at the Apache error log which is located at <code>/var/log/apache2/error.log</code>.<br />
<br />
$ cd /etc/apache2/<br />
$ diff apache2.conf apache2.conf.bak1<br />
$ cd /opt/webwork/webwork2/conf/<br />
$ diff site.conf site.conf.dist<br />
$ diff localOverrides.conf localOverrides.conf.dist<br />
$ diff webwork.apache2.4-config webwork.apache2.4-config.dist<br />
$ tail /var/log/apache2/error.log <br />
<br />
If something is wrong and you fix it, you will have to restart Apache for the changes to take effect<br />
<br />
$ sudo systemctl restart apache2<br />
[sudo] password for wwadmin: <wwadmin password><br />
<br />
== Create the admin Course ==<br />
<br />
[[Course Administration]] gives information about creating courses. Here we will give explicit instructions for doing this. (You may need to become root or use sudo to execute some of these commands.)<br />
<br />
$ cd /opt/webwork/courses<br />
$ /opt/webwork/webwork2/bin/addcourse admin --db-layout=sql_single --users=adminClasslist.lst --professors=admin<br />
$ sudo chown -R www-data:www-data admin <br />
[sudo] password for wwadmin: <wwadmin password><br />
<br />
where the last line makes the course <code>admin</code> and its subdirectories owned by the Apache server and readable/writeable by the WWADMIN user.<br />
<br />
Now goto <code>http://yourserver.yourschool.edu/webwork2</code> and should see the WeBWorK home page with <code>Course Administration</code> listed at the top. Click on it and login with Username <code>admin</code> and Password <code>admin</code> . This first thing you should do is register your new WeBWorK installation. It's quick and easy, just click on <code>Register</code>. '''IMPORTANT''' The next thing you should do is click on <code>User Settings</code> and change <code>admin</code> 's password to something more secure than <code>admin</code> . <br />
<br />
Unless you choose otherwise, users with <code>admin</code> privileges in the <code>admin</code> course (i.e. WeBWorK administrators) will automatically be added to new courses with <code>admin</code> privileges and the same password as in the <code>admin</code> course. Initially the only such user is <code>admin</code> (hopefully you are not confused by the fact that the course <code>admin</code> has a user named <code>admin</code>). It's usually convenient make yourself a WeBWorK administrator. To do this (assuming you are logged in as <code>admin</code> to the <code>admin</code> course at <code>http://yourserver.yourschool.edu/webwork2/admin</code> )<br />
# Click on <code>Classlist Editor</code> in the left panel<br />
# Click the <code>Add</code> tag and click <code>Take Action!</code><br />
# Enter the appropriate information (you can use your <code>Login Name</code> as the <code>Student ID</code> if you want and also you can leave the last three items blank) and click <code>Add Students</code><br />
# Click on <code>Classlist Editor</code> in the left panel again<br />
# When you enter a new student, by default their <code>Student ID</code> is used as their password. We'll change this now.<br />
# Select yourself with a check mark and click the <code>Password</code> tag and click <code>Take Action!</code>. (Note as a safely mechanism you can not change the password for the user you are logged in as, currently <code>admin</code>, this way) <br />
# Enter the password and then click <code>Take Action!</code><br />
# Finally give yourself <code>admin</code> privileges by selecting yourself with a check mark, clicking the <code>Edit</code> tag and then clicking <code>Take Action!</code> (or by just clicking on the "pencil" next to your login name which is a much faster way to edit classlist data for a single user)<br />
# Now at the far right change <code>Permission Level</code> from <code>student</code> to <code>admin</code><br />
# Then click <code>Take Action!</code><br />
<br />
At some point you will probably want to hide the <code>admin</code> course so that it is not listed on the WeBWorK home page. As we noted above the <code>modelCourse</code>, which is already hidden, is not a real course so you will get an error message if you try to log into it. This is a good reason to hide it. The <code>modelCourse</code> is very useful as a model (hence its name) for setting up other courses. The <code>admin</code> course is used for administering WeBWorK and even though regular users can not log into it (you did change the <code>admin</code> password, didn't you!!), it a little bit cleaner and safer to hide it from prying eyes. <br />
To hide (or unhide) a course select <code>Hide Inactive courses</code> in the admin course and follow the directions. When hidden a course will not show up in the courses list on the WeBWorK home page. It will still appear in the Course Administration listing. If you do this you will still be able to access the <code>admin</code> course using the URL <code>http://yourserver.yourschool.edu/webwork2/admin</code> but you will not see a link for it on the WeBWorK home page <code>http://yourserver.yourschool.edu/webwork2</code> . <br />
<br />
<br />
Now goto <code>http://yourserver.yourschool.edu/webwork2</code> and no course will be listed.<br />
<br />
==Checking for and Installing Hotfixes==<br />
<br />
The following commands show you how to check for and install bug fixes. '''Important Note:''' These commands check and retrieve the master branch which gives the latest stable release of the software package (webwork2, pg, etc.) with bug fixes. If a stable release newer than 2.15 exists for webwork2 and/or pg, that will be checked and retrieved which is probably not what you want. Please check before updating. The best way to do that is to look at https://github.com/openwebwork/webwork2/blob/master/VERSION and https://github.com/openwebwork/pg/blob/master/VERSION.<br />
<br />
To check if there are bug fixes, do the following. <br />
===Updating the webwork2 code===<br />
<br />
First we check for updates to the webwork2 code:<br />
cd /opt/webwork/webwork2/<br />
git remote show origin<br />
This will print several lines of data, but the last line will tell you if your copy is up to date or out of date. If it is out of date, run<br />
git pull origin and restart apache2.<br />
<br />
===Updating the pg code===<br />
<br />
Now check for updates to the pg code:<br />
cd /opt/webwork/pg/<br />
git remote show origin<br />
This will print several lines of data, but the last line will tell you if your copy is up to date or out of date. If it is out of date, run<br />
git pull origin<br />
and restart apache2.<br />
<br />
===Restart apache2===<br />
<br />
'''Important:''' After updating either webwork2 or pg, you have to restart apache2<br />
$ sudo apache2ctl restart<br />
password:<wwadmin password><br />
<br />
===Updating the OPL===<br />
<br />
The following assumes you have already installed the OPL. For that see [[#Install the Open Problem Library]] below.<br />
Now check for updates to the Open Problem Library:<br />
cd /opt/webwork/libraries/webwork-open-problem-library<br />
git remote show origin<br />
This will print several lines of data, but the last line will tell you if your copy is up to date or out of date. If it is out of date, run<br />
git pull origin<br />
Then rerun the <code>OPL-update</code> script. Updating the OPL is pretty much risk free since changes usually involve only a relatively small <br />
number of individual problems and the vast majority of problems remain unchanged. Updating the OPL does not require restarting apache2.<br />
<br />
$ OPL-update<br />
<br />
== Starting and Stopping Apache and MySQL ==<br />
If you make changes to the system, you will have to restart <code>apache2</code> before the changes take effect. On rare occasions you may need to restart <code>MySQL</code>. <br />
=== Starting and Stopping Apache ===<br />
You have to run these commands as <code>root</code>.<br />
<br />
To start or restart (i.e. stop and then start) the <code>apache2</code> webserver run the command <br />
$ sudo apache2ctl graceful<br />
[sudo] password for wwadmin: <wwadmin password><br />
You can also start <code>apache2</code> by<br />
$ sudo apache2ctl start<br />
[sudo] password for wwadmin: <wwadmin password><br />
and restart it with<br />
$ sudo apache2ctl restart<br />
[sudo] password for wwadmin: <wwadmin password><br />
<code>restart</code> is less graceful but more powerful than <code>graceful</code>. Sometimes <code>graceful</code> fails to kill all <code>apache2</code> child processes. <br />
<br />
<br />
To stop the Apache webserver run the command <br />
<br />
$ sudo apache2ctl stop<br />
[sudo] password for wwadmin: <wwadmin password><br />
<br />
Stopping and then starting Apache should definitely kill all <code>apache2</code> child processes. <br />
<br />
You can also start or stop apache2 by using the <code>apache2</code> service. Run<br />
$ sudo service apache2<br />
[sudo] password for wwadmin: <wwadmin password><br />
<br />
and you will get a list of allowed commands (<code>start</code>, <code>stop</code>, <code>restart</code>, etc.).<br />
<br />
Finally you can use the newer <code>systemctl</code> method, e.g.<br />
sudo systemctl start apache2<br />
[sudo] password for wwadmin: <wwadmin password><br />
<br />
sudo systemctl --help <br />
will give you a list of all possible commands, the main ones being <code>start</code>, <code>stop</code>, <code>restart</code> and <code>status</code>.<br />
<br />
Note that <code>systemctl</code> is the preferred method on modern versions of Ubuntu.<br />
<br />
=== Starting and Stopping MySQL or MariaDB ===<br />
You have to run these commands as <code>root</code>.<br />
<br />
To start the <code>MySQL</code> server run the command <br />
$ sudo systemctl start mysql<br />
<br />
To stop the <code>MySQL</code> server run the command <br />
$ sudo systemctl stop mysql<br />
<br />
To restart the <code>MySQL</code> server run the command <br />
$ sudo systemctl restart mysql<br />
<br />
To obtain more information about the mysql server run<br />
$ systemctl status mysql <br />
<br />
To get a list of all possible commands run <br />
$ systemctl --help<br />
<br />
==Install the WeBWorK Problem Libraries ==<br />
Before we create a real course we will install the WeBWorK Problem Libraries.<br />
<br />
===Install the Open Problem Library ===<br />
The <code>Open Problem Library</code> consists of both WeBWorK problems and methods for searching and selecting problems. Also it contains as sub libraries many of the other standard libraries. We have to load a database for searching it.<br />
<br />
First we put a link to the Open Problem Library in the modelCourse so that when we create courses copying templates from the modelCourse, the OPL will be available.<br />
<br />
$ cd /opt/webwork/courses/modelCourse/templates/<br />
$ ln -s /opt/webwork/libraries/webwork-open-problem-library/OpenProblemLibrary Library<br />
<br />
Note that if the above link is not in the templates directory of a course, it will be automatically created when you open the Library Browser. However, <br />
if e.g. you haven't yet opened the Library Browser and the link is missing and you import problem sets (as we do in section [[#Test that Things are Working Properly|Test that Things are Working Properly]] below), you may see errors <br />
when viewing problems (you definitely will see errors in the Orientation set).<br />
<br />
Next we have to run the <code>OPL-update</code> script which will create the data that the Library Browser uses.<br />
<br />
$ OPL-update<br />
<br />
This has to convert a lot of data for over 37,000 problems so please be patient; it can take a long time.<br />
<br />
If at some time in the future you want to upgrade the Problem Library, the process<br />
is easy, see [[#Updating the OPL|Updating the OPL]]. Note that this is something you should do fairly often so that your library is up to date with<br />
new problems and bug fixes for old ones.<br />
<br />
===Initialize the OPL local statistics database table===<br />
Run the command<br />
$ update-OPL-statistics.pl<br />
to create a table to hold the OPL local statistics. See https://webwork.maa.org/wiki/OPL_Problem_Statistics for information.<br />
<br />
===Set up the access to the Contrib directory ===<br />
<br />
The <code>Contrib</code> directory contains contributions to the OPL that may not have been formally accepted into the main collection of OPL problems. This may be because the contribution is recent and has not yet been reviewed or because the problems are not properly tagged as is the case with the CAPA problem collection. It also contains the original versions of problems that have been accepted into the OPL (the idea being that the original authors maintain control of problems in the <code>Contrib</code> directory but problems in the OPL are controled by the editors). This step creates a button in the Library Browser which gives a direct link to the <code>Contrib</code> directory.<br />
<br />
<br />
Put a link to the Contrib directory in the <code>modelCourse</code> so that when we create courses copying templates from the <code>modelCourse</code>, the Contrib directory will be available. <br />
<br />
$ cd /opt/webwork/courses/modelCourse/templates/<br />
$ ln -s /opt/webwork/libraries/webwork-open-problem-library/Contrib Contrib<br />
<br />
If you just want to do this for individual courses, not all courses then don't put the link in the <code>modelCourse</code> above, and then do the following. Note we don't have any individual courses yet. But for example after creating <code>myTestCourse</code> below, to set up access to the <code>Contrib</code> directory from <code>myTestCourse</code>, do the following<br />
$ cd /opt/webwork/courses/myTestCourse/templates/<br />
$ sudo $ ln -s /opt/webwork/libraries/webwork-open-problem-library/Contrib Contrib<br />
[sudo] password for wwadmin: <wwadmin password><br />
<br />
===Set up the Rochester and Union Libraries ===<br />
<br />
This step is optional. It creates buttons in the Library Browser which give direct links to the Rochester and Union libraries. If you don't do this, you can find these libraries and others under the <code>OPL Directory</code> button.<br />
<br />
First we need to edit <code>localOverrides.conf</code> one last time<br />
<br />
$ cd /opt/webwork/webwork2/conf<br />
$ nano localOverrides.conf<br />
<br />
Search for <code>courseFiles{problibs}</code> and scroll down several lines to the lines<br />
# rochesterLibrary =&gt; "Rochester",<br />
# unionLibrary =&gt; "Union",<br />
Uncomment these lines (i.e. remove the <code>#</code>) so they become <br />
rochesterLibrary =&gt; "Rochester",<br />
unionLibrary =&gt; "Union",<br />
Then save the file and quit.<br />
<br />
We next put links to the Rochester and Union Libraries in the <code>modelCourse</code> so that when we create courses copying templates from the <code>modelCourse</code>, these libraries will be available. Skip this step if you usually only want to use Open Problem Library. Note that the Rochester, Union and other libraries are contained in the OPen Problem Library and are accessible from there under the <code>OPL Directory</code> button in the Library Browser. This step simply creates buttons in the Library Browser so that you can access the Rochester and Union libraries directly.<br />
<br />
$ cd /opt/webwork/courses/modelCourse/templates/<br />
$ ln -s /opt/webwork/libraries/webwork-open-problem-library/OpenProblemLibrary/Union unionLibrary<br />
$ ln -s /opt/webwork/libraries/webwork-open-problem-library/OpenProblemLibrary/Rochester rochesterLibrary<br />
<br />
If you want to put another library into the <code>modelCourse</code>, just do the analogous thing. If you just want the additional library in a particular course, add the link in the <code>templates</code> directory of that course. If you look in the directory <code>/opt/webwork/libraries/webwork-open-problem-library/OpenProblemLibrary/</code> you might find other libraries that are not yet listed in <code>global.conf</code> and these can be added in the same way as the <code>Rochester and </code><code>Union</code> libraries. Finally if you add a library with non standard symbols in the name (e.g. <code>uva-statLibrary</code>) you have to use single quotes when adding it to <code>global.conf</code>, e.g. <br><br />
&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp; <code>'uva-statLibrary' => "UVA-Stat",</code> <br><br />
It's easier to just avoid such names.<br />
<br />
===Install and Set Up the CAPA Library ===<br />
<br />
This step is optional. It installs and sets up [[CAPA Physics Problems|the CAPA Library]], which is a library of physics problems.<br />
<br />
'''Note:''' We are in the process of integrating the CAPA problems into the main distribution so some of the details below may change.<br />
<br />
Move the CAPA graphics files to the required locations and set the group.<br />
<br />
$ cd /opt/webwork/libraries/webwork-open-problem-library/Contrib/CAPA <br />
$ mv CAPA_Graphics /opt/webwork/webwork2/htdocs/<br />
$ sudo chgrp -R wwdata /opt/webwork/webwork2/htdocs/CAPA_Graphics<br />
[sudo] password for wwadmin: <wwadmin password><br />
$ sudo chmod -R g+w /opt/webwork/webwork2/htdocs/CAPA_Graphics <br />
<br />
We need to edit <code>localOverrides.conf</code> again<br />
<br />
$ cd /opt/webwork/webwork2/conf<br />
$ nano localOverrides.conf<br />
<br />
<br />
Now search for the lines<br />
$pg{specialPGEnvironmentVars}{CAPA_Tools} = "$courseDirs{templates}/Contrib/CAPA/macros/CAPA_Tools/",<br />
$pg{specialPGEnvironmentVars}{CAPA_MCTools} = "$courseDirs{templates}/Contrib/CAPA/macros/CAPA_MCTools/",<br />
$pg{specialPGEnvironmentVars}{CAPA_GraphicsDirectory} = "$courseDirs{templates}/Contrib/CAPA/CAPA_Graphics/",<br />
push @{$pg{directories}{macrosPath}},<br />
"$courseDirs{templates}/Contrib/CAPA/macros/CAPA_Tools",<br />
"$courseDirs{templates}/Contrib/CAPA/macros/CAPA_MCTools";<br />
<br />
and replace these six lines by<br />
<br />
################################################################################<br />
#Locations of CAPA resources. (Only necessary if you need to use converted CAPA problems.)<br />
################################################################################<br />
$pg{specialPGEnvironmentVars}{CAPA_Tools} = "$courseDirs{templates}/Contrib/CAPA/macros/CAPA_Tools/",<br />
$pg{specialPGEnvironmentVars}{CAPA_MCTools} = "$courseDirs{templates}/Contrib/CAPA/macros/CAPA_MCTools/",<br />
$pg{specialPGEnvironmentVars}{CAPA_GraphicsDirectory} = "$webworkDirs{htdocs}/CAPA_Graphics/";<br />
$pg{specialPGEnvironmentVars}{CAPA_Graphics_URL} = "$webworkURLs{htdocs}/CAPA_Graphics/";<br />
<br />
<br />
<br />
<br />
Then save the file and Quit.<br />
<br />
There is one final step that is needed. We have to put a link in the templates directory of every course that needs access to the CAPA Library. If you want to have every course you create have access to the CAPA Library (unlikely unless you are in a physics department) put the link in the <code>modelCourse</code>. <br />
$ cd /opt/webwork/courses/modelCourse/templates/<br />
$ ln -s /opt/webwork/libraries/webwork-open-problem-library/Contrib/CAPA/ capaLibrary<br />
<br />
More likely if you just want to do this for individual courses, not all courses then don't put the link in the <code>modelCourse</code> above, and then do the following. We don't have any yet. But for example after creating <code>myTestCourse</code> below, to set up access to the CAPA Library from <code>myTestCourse</code>, do the following<br />
$ cd /opt/webwork/courses/myTestCourse/templates/<br />
$ sudo ln -s /opt/webwork/libraries/webwork-open-problem-library/Contrib/CAPA/ capaLibrary<br />
[sudo] password for wwadmin: <wwadmin password><br />
<br />
<br />
and do the analogous thing for every course that needs access to the CAPA Library.<br />
Then to gain access to the CAPA Library from the course, simply go to the <code>Library Browser</code> and click on the <code>CAPA</code> button.<br />
<br />
<br />
<br />
==Create Your First Actual Course ==<br />
<br />
Since we have edited <code>site.conf</code> and <code>localOverrides.conf</code> and these are critical files, it would be a good idea to run<br />
$ cd /opt/webwork/webwork2/conf<br />
$ diff site.conf site.conf.dist<br />
$ diff localOverrides.conf localOverrides.conf.dist<br />
<br />
and check that you haven't made any mistakes (e.g. by introducing an inadvertent line break, etc.). If there are any mistakes, correct them. Remember that any time you change either of these files you must restart the Apache webserver in order for these changes to take effect. <br />
<br />
Since we have edited <code>global.conf</code> and haven't restarted Apache we do so now.<br />
$ sudo apache2ctl graceful<br />
password:<wwadmin password><br />
<br />
Now log into the <code>admin</code> course ( <code>http://yourserver.yourschool.edu/webwork2/admin</code> or, if you have not hidden the admin course, click on <code>Course Administration</code> on WeBWorK's home page <code>http://yourserver.yourschool.edu/webwork2/</code> ) as yourself or <code>admin</code> and <br />
# click on <code>Add Course</code><br />
# For <code>Course ID</code> enter <code>myTestCourse</code><br />
# For <code>Course Title</code> enter <code>My Test Course</code><br />
# Enter your institution<br />
# Leave <code>Add WeBWorK administrators to new course</code> checked<br />
# Add an additional instructor if you wish<br />
# Copy templates from: <code>modelCourse</code> (the default action)<br />
# Click on <code>Add Course</code><br />
# Click <code>Log into myTestCourse</code><br />
<br />
and log in either as <code>admin</code> or yourself (if you added yourself as an additional instructor above).<br />
<br />
At some point you will probably want to "hide" <code>myTestCourse</code> from general view but you already know how to do that.<br />
<br />
==Test that Things are Working Properly ==<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>.<br />
<br />
Click on <code>Hmwk Sets Editor</code> on the <code>Main Menu</code>. Then select <code>Import</code>, select <code>setDemo.def</code> from the <code>from</code> drop down list and select <code>all current users</code> from the <code>assigning this set to</code> drop down list. Then hit <code>Take Action!</code><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. If not, edit the file <code>Constants.pm</code> in the directory <code>/opt/webwork/webwork2/lib/WeBWorK</code>. Change the line <code>$WeBWorK::PG::ImageGenerator::PreserveTempFiles = 0;</code> to <code>...::PreserveTempFiles = 1;</code>. Then restart Apache and view the first couple problems or some new ones. Then look in the directory <code>/opt/webwork/webwork2/tmp/</code>. <code>cd</code> to one of the <code>ImageGenerator.../tmp/</code> directories and look at the error and log files there. When you fix the problem remember to edit <code>...::PreserveTempFiles = 1;</code> back to 0 and restart Apache or you will be saving a lot of unnecessary files. Another useful trick is to try downloading a hard copy of an assignment and then (assuming there are errors) looking at the various log files that are linked to on the output page.<br />
<br />
Note that since you probably used "admin" to login you have Permission Level "admin" so things look more complicated than if you were just a regular professor with Permission Level "professor". In particular any time you view a problem, you have the option to "Edit tags" which you probably do not want to do. If these bothers you, login as a professor (see below).<br />
<br />
Continue looking at problems to see if everything is working properly.<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 an admin 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>. If you get an error (you shouldn't) just click <code>Download Hardcopy</code> to get what was generated. Also you can see links to various informational files that are available if you run into problems (normally these files are removed if there are no errors). If you want to preserve these tmp files, set <code>$WeBWorK::ContentGenerator::Hardcopy::PreserveTempFiles</code><br />
to 1 in the file <code>Constants.pm</code> in the directory <code>/opt/webwork/webwork2/lib/WeBWorK</code> and then restart Apache. Remember to set this back to 0 after debugging.<br />
<br />
Another thing to do is to use <code>Email</code> on the <code>Main Menu</code>. Again this page is a little complicated because you can do a lot of things with it (including mail merge) but at this point just select yourself in the list to the right and hit <code>Send Email</code> at the bottom. You should receive two emails. One is the message you just sent and the other is an email with subject "WeBWorK email sent" giving information on your mailing. <br />
<br />
As a final test 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. You can also test that you can access any additional Problem Libraries that you installed. Note that if you just happen to view some statistics problems that require the R server, you will get errors (since we have not installed R --- at least not yet).<br />
<br />
'''Note:''' if when using the <code>Library Browser</code> you find that after selecting a <code>Subject</code>, you can not select a <code>Chapter</code> (and usually you will see an error from setmaker.js: /webwork2/instructorXMLHandler: e.g. Timeout or Forbidden),<br />
the most common reason is that $server_root_url has not been set "correctly" in the <code>/opt/webwork/webwork2/conf/site.conf</code> file. A common error is to use forget http:// or to use http:// when you should use https:// or to just have the wrong domain name or ip address. But sometimes "localhost" will work when the correct ip address or url will not, for example in situations when you are using a virtual machine as your host (e.g. on AWS).<br />
<br />
If all the above tests work, you can be pretty confident that WeBWorK is working properly.<br />
<br />
Go back to <code>Hmwk Sets Editor</code> on the <code>Main Menu</code>. Then select <code>Import</code>, select <code>setOrientation.def</code> from the <code>from</code> drop down list and select <code>all current users</code> from the <code>assigning this set to</code> drop down list. Then hit <code>Take Action!</code>. Then go through the Orientation problems. This is a good first set to use for introducing students to WeBWorK. Also you can Import <code>set0.def</code> and <code>setMAAtutorial.def</code> and look through those problems.<br />
<br />
If you are new to WeBWorK or even if you are a pro, you should probably add a regular student to myTestCourse and log in as that student to see what the student interface looks like. It's much simpler than the professor or admin interfaces. Also for the same reason you should probably add professor to myTestCourse and log in as that professor to see what the professor interface looks like.<br />
<br />
Click on <code>Classlist Editor</code> on the <code>Main Menu</code>.<br />
Then select <code>Add</code>, for "Add how many students?" pick 2 and hit <code>Take Action!</code>. Then add two students, say <br />
<br />
* <code>Last Name</code> "Smith", <code>First Name</code> "Jane" , <code>Student ID</code> "jsmith" and <code>Login Name</code> "jsmith"<br />
<br />
* <code>Last Name</code> "A", <code>First Name</code> "Prof" , <code>Student ID</code> "profa" and <code>Login Name</code> "profa"<br />
and make sure to select all sets to assign them to both of them. Then hit <code>Add Students</code>.<br />
<br />
Now we make "profa" a professor. Again click on <code>Classlist Editor</code> on the <code>Main Menu</code>. The fast way is to click on the "pencil" by "profa", set the "Permission Level" to "professor" and hit <code>Take Action!</code>.<br />
<br />
Jane Smith's initial password will be her <code>Student ID</code> <code>jsmith</code>. Now login as Jane Smith and play around a little. <br />
<br />
Prof A's initial password will be her <code>Student ID</code> <code>profa</code>. You should also login as Prof A and play around a little. <br />
<br />
You can also add "practice users" and login as one of those to see how you can grant partial access to your course for practice or other reasons (e.g. auditors who don't want to be graded). To do this Click on <code>Classlist Editor</code>, select <code>Import</code>, select the "demoCourse.lst" (the only classlist available at this point) and hit <code>Take Action!</code>.<br />
<br />
==Optional Configurations==<br />
*'''Optional A''' stores WeBWorK's "temporary" files in a separate partition (or directory). <br />
*'''Optional B''' installs and configures a lightweight webserver to serve static files.<br />
*'''Optional C''' configures Apache so that access to WeBWorK will be through SSL.<br />
*'''Optional D''' installs and configures the R server for statistical computing.<br />
*'''Optional E''' sets up log rotation for WeBWorK's timing log.<br />
<br />
===Implement Optional A (wwtmp)===<br />
<br />
Now is the time to implement '''Optional A''' if you choose to do so. Actually you can do this at any time and your active courses will continue to function seemingly without change. The only change behind the scenes will be that temporary files will be stored in a different location. Note that if you want to use this option but did not create <code>wwtmp</code> as a separate partition, you first have to create the directory <code>/var/www/html/wwtmp</code> with the command<br />
sudo mkdir /var/www/html/wwtmp <br />
[sudo] password for wwadmin: <wwadmin password><br />
All of WeBWorK's "temporary" files will be stored under <code>/var/www/html/wwtmp</code>. These are mostly small files such as png images of equations, pdf files, etc. that may be reused but if they are not present (e.g. if they get deleted) they will be seamlessly regenerated on the fly. There is no reason to back up such files and having them in a separate partition or directory means that it is easier and faster to back up other partitions and skip backing up unnecessary files. Even if you do not want to set up a separate partition for this, it is very convenient to at least set up a separate directory for these temporary files and we recommend that yo do so.<br />
<br />
First we set the group and permissions for the <code>wwtmp</code> directory<br />
$ sudo -s<br />
[sudo] password for wwadmin: <wwadmin password><br />
# cd /var/www/html<br />
# chown wwadmin wwtmp<br />
# chgrp wwdata wwtmp<br />
# chmod ug+w wwtmp<br />
# chmod g+s wwtmp<br />
# exit<br />
$<br />
Next we have to edit <code>localOverrides.conf</code> so that WeBWorK uses the new <code>wwtmp</code> directory. Since we have a working WeBWorK system, first we make a backup copy of <code>localOverrides.conf</code>.<br />
$ cd /opt/webwork/webwork2/conf<br />
$ cp localOverrides.conf localOverrides.conf.bak1<br />
$ nano localOverrides.conf<br />
Now edit <code>localOverrides.conf</code>. Search for the line<br />
# Directory for temporary files<br />
and under that find the line<br />
# To implement, uncomment the following 6 lines:<br />
Then uncomment (i.e. remove the # symbol) from the 6 lines<br />
#$webworkDirs{htdocs_temp} = '/var/www/html/wwtmp';<br />
#$webworkURLs{htdocs_temp} = '/wwtmp';<br />
#$webworkDirs{equationCache} = "$webworkDirs{htdocs_temp}/equations";<br />
#$webworkURLs{equationCache} = "$webworkURLs{htdocs_temp}/equations";<br />
#$courseDirs{html_temp} = "/var/www/html/wwtmp/$courseName";<br />
#$courseURLs{html_temp} = "/wwtmp/$courseName";<br />
<br />
'''IMPORTANT NOTE'''. Apache 2.4 has changed the default location of the document root from <code>/var/www</code> to <br />
<code>/var/www/html</code> and we are in the process of updating the file <code>localOverrides.conf.dist</code> to reflect this.<br />
If your copy of this file does not have <code>/html</code> in the two lines above, then in addition to uncommenting the 6 lines you also have to add <code>/html</code> in two places.<br />
<br />
Then save the file and quit. If you look at the <code>wwtmp</code> directory you will find it empty but after you restart apache and then access some WeBWorK problems, you will find temporary directories and files in <code>wwtmp</code>. Remember your have to restart apache for these changes to take effect.<br />
<br />
====Using Cron Jobs to remove temporary files====<br />
<br />
It is a good idea to clean out temporary files on a regular automatic schedule. Also pdf copies of downloaded problem sets are saved in a temporary directory (<code>wwtmp/.../hardcopy</code>) so that they can be downloaded from the web. But after the download, the pdf file remains and is visible from the web if one knows the URL. For this reason we recommend deleting all such files that are over one hour old. Similarly we recommend deleting all png, gif, and html links under <code>wwtmp</code> that are over 30 days old. And finally every week we recommend deleting all equation images that are over 14 days old. The following cron jobs will accomplish this. The first is run every 30 minutes, the next three twice a month and the last one weekly on Sunday morning. These cron jobs should be run as root. We use <code>crontab</code> to edit the <code>crontab</code> file:<br />
$ sudo -s<br />
[sudo] password for wwadmin: <wwadmin password><br />
# crontab -e<br />
<br />
Now add the following lines at the end of the file<br />
<br />
WEBWORK_ROOT=/opt/webwork/webwork2<br />
*/30 * * * * find /var/www/html/wwtmp/*/hardcopy/* -mmin +60 -name "*" -delete<br />
5 5 1,15 * * find /var/www/html/wwtmp/*/gif/ -mtime +30 -name "*" -delete<br />
5 5 2,16 * * find /var/www/html/wwtmp/*/png/ -mtime +30 -name "*" -delete<br />
5 5 3,17 * * find /var/www/html/wwtmp/*/html/ -mtime +30 -name "*" -delete<br />
4 5 * * 0 /opt/webwork/webwork2/bin/remove_stale_images --delete --days 14<br />
<br />
and save the file and quit<br />
# exit<br />
$<br />
<br />
===Implement Optional B (lighttpd)===<br />
<br />
As is the case for '''Optional A''' you can implement '''Optional B''' at any time and your active courses will continue to function seemingly without change. The only change behind the scenes will be that static images, pages and MathJax (if you installed it locally) will be served by a light weight web server.<br />
====Install and Configure lighttpd====<br />
First we install the light weight webserver <code>lighttpd</code><br />
<br />
Run the command <br />
$ sudo apt install lighttpd<br />
[sudo] password for wwadmin: <wwadmin password><br />
<br />
Now we configure <code>lighttpd</code>. First let's make a backup of the configuration file.<br />
<br />
<br />
$ cd /etc/lighttpd<br />
$ sudo cp lighttpd.conf lighttpd.conf.bak1<br />
[sudo] password for wwadmin: <wwadmin password><br />
<br />
Now edit <code>lighttpd.conf</code>. <br />
<br />
$ sudo nano lighttpd.conf<br />
<br />
<br />
Apache2 is listening on port 80 so we need an alternate port for lighttp to listen to. Standard alternate ports for this are usually 81, 8000, or 8080. 8080 is the only port that is listed as an official alternate at http://en.wikipedia.org/wiki/List_of_TCP_and_UDP_port_numbers . Note that in rare cases an institution may block httpd requests to port 8080. If any of your students report that they can not see graphics, they will have to request that access to requests to port 8080 be allowed.<br />
<br />
Find the line<br />
server.port = 80<br />
and replace it by<br />
server.port = 8080<br />
<br />
Now we make a few more changed that allow MathJax to run under lighttpd. You can skip these if you are running MathJax remotely. At the top of the file in the section <code> server.modules = </code>, under the line<br />
"mod_redirect",<br />
add the line<br />
"mod_setenv",<br />
Then below the closing parentheses and above the line <br />
server.document-root = "/var/www/html"<br />
add the lines<br />
setenv.add-response-header = ( "Access-Control-Allow-Origin" => "*" )<br />
alias.url = ( "/webwork2_files" => "/opt/webwork/webwork2/htdocs/" )<br />
<br />
Then save the file and quit.<br />
<br />
Now restart lighttp<br />
$ sudo systemctl restart lighttpd<br />
<br />
====Test lighttpd====<br />
First run the command<br />
$ sudo lsof -i -P -n | grep LISTEN<br />
and check that lighttpd is listening on port 8080<br />
<br />
Now test your server by connecting to your<br />
server from a browser on a remote machine ("http://yourserver.yourschool.edu:8080/"). You should see the '''Apache2 Ubuntu Default Page''' but without a graphic for the Ubuntu Logo indicating that lighttp is running . Test the <code>/webwork2_files</code> location by visiting "http://yourserver.yourschool.edu:8080/webwork2_files</code>. You should see the "WeBWorK Placeholder Page".<br />
<br />
====Configure WeBWorK to Take Advantage of Lighttp====<br />
<br />
First let's make a backup copy of <code>localOverrides.conf </code> so that we can easily back out of these changes if necessary.<br />
<br />
$ cd /opt/webwork/webwork2/conf<br />
$ cp localOverrides.conf localOverrides.conf.bak2<br />
<br />
<br />
Now edit <code>localOverrides.conf</code>. Note that while '''Optional B''' is independent of '''Optional A''', we assume most people implementing '''Optional B''' will have already implemented '''Optional A'''. Therefore we give instructions for editing <br />
localOverrides.conf assuming that '''Optional A''' has been implemented. If this is not the case, modify the instructions below accordingly. Also replace <code>yourserver.yourschool.edu</code> with the correct address.<br />
<br />
$ nano localOverrides.conf<br />
<br />
Find the line<br />
$webworkURLs{htdocs_temp} = '/wwtmp'<br />
and replace it by<br />
#$webworkURLs{htdocs_temp} = '/wwtmp';<br />
$webworkURLs{htdocs_temp} = 'http://yourserver.yourschool.edu:8080/wwtmp';<br />
<br />
<br />
Find the line<br />
$courseURLs{html_temp} = "/wwtmp/$courseName";<br />
and replace it by<br />
#$courseURLs{html_temp} = "/wwtmp/$courseName";<br />
$courseURLs{html_temp} = "http://yourserver.yourschool.edu:8080/wwtmp/$courseName";<br />
<br />
If you installed MathJax locally under the above line add the lines<br />
# Location of MathJax script, used for the MathJax display mode.<br />
$webworkURLs{MathJax} = 'http://yourserver.yourschool.edu:8080/webwork2_files/mathjax/MathJax.js?config=TeX-MML-AM_HTMLorMML-full';<br />
If you are running MathJax remotely, '''don't add the above lines'''.<br />
<br />
Then save the file and quit.<br />
<br />
Now restart apache and lighttp.<br />
<br />
$ sudo apache2ctl graceful<br />
password:<wwadmin password><br />
$ sudo systemctl restart lighttpd<br />
<br />
====Test that Everything is Working Properly====<br />
<br />
To test things go to your test course <code>http://yourserver.yourschool.edu/webwork2/myTestCourse/</code>. Log into your course and view a problem with a graphic image (e.g. Problem 2 of the Demo set. Since you have Admin or Prof privileges, you can view sets which are not yet open). Right click on the image and click on Properties (or whatever is appropriate on your browser, e.g. copy image location) and check that the image is being served from port 8080 (something like <code>http://yourserver.yourschool.edu:8080/wwtmp/myTestCourse//gif/...</code>). <br />
<br />
If MathJax is installed locally, to test that MathJax is using lighttpd, view a problem with some typeset equations. Right click on the equation and you should see the MathJax menu which confirms MathJax is being used. Next look at the source code for the page (e.g. right click on most browsers and select "View page source") and in the source, search for mathjax.js. You should see that this is being loaded from port 8080. Obviously, if you are running MathJax remotely, you will see it is being loaded from the CDN.<br />
<br />
====Disabling Optional B (lighttpd) for a single course====<br />
<br />
If your server is hosting courses from different institutions, you may find that you need to disable using lighttpd for a single course, e.g. because the institution blocks access to port 8080. Actually since port 8080 is an "official" alternate httpd port, you should first try to get the network administrators at the institution to grant access to port 8080. Failing this, you can disable using lighttpd and instead use apache for a single course by adding the following lines to the end of the course's <code>course.conf</code> file which is located in the top level directory for the course (usually <code>/opt/webwork/courses/course_name</code>). Note that using apache instead of lighttpd will put a slightly larger load on the server. Also note that you need "admin" level privileges to edit the <code>course.conf</code> file. Instructors with only "professor" level privileges can not do this from within WeBWorK.<br />
If you are running MathJax remotely, don't add the last line.<br />
# Do not use lightppd (port 8080) for this course<br />
$webworkURLs{htdocs_temp} = '/wwtmp';<br />
$courseURLs{html_temp} = "/wwtmp/$courseName";<br />
$webworkURLs{equationCache} = "$webworkURLs{htdocs_temp}/equations";<br />
$webworkURLs{MathJax} = "$webworkURLs{htdocs}/mathjax/MathJax.js?config=TeX-MML-AM_HTMLorMML-full";<br />
'''I repeat if you are running MathJax remotely, don't add the last line above.'''<br />
<br />
===Implement Optional C (SSL)===<br />
'''Optional C''' configures apache so that access to WeBWorK will be through an encrypted connection (SSL) with an https: URL. 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. If you have implemented '''Optional B''', the non encrypted lighttpd server will be used for images, MathJax, etc. so we might have to set up the lighttpd server to run under SSL (see below).<br />
<br />
First we have to obtain an official SSL certificate or generate a self-signed one which can be used for testing purposes. If students will be using your server, it is better to obtain an official SSL certificate since using a self-signed certificate with cause warning messages to be displayed when students connect to the server.<br />
<br />
====Obtain an Official SSL Certificate====<br />
Talk to the networking group on your campus about obtaining an official certificate. You can find information on the net about certificate providers, e.g. http://www.sslshopper.com/certificate-authority-reviews.html .<br />
<br />
The certificate goes in <code>/etc/ssl/certs/</code> and the key file goes in <code>/etc/ssl/private/</code>.<br />
<br />
====Use a self-signed Certificate====<br />
<br />
When we installed the package openssh-server a self-signed certificate was automatically created. The certificate is stored at<br />
/etc/ssl/certs/ssl-cert-snakeoil.pem<br />
and the private key at<br />
/etc/ssl/private/ssl-cert-snakeoil.key<br />
<br />
This certificate and key may be regenerated manually with the following command (needs root privileges ie sudo):<br />
<br />
$ sudo make-ssl-cert generate-default-snakeoil --force-overwrite<br />
[sudo] password for wwadmin: <wwadmin password><br />
<br />
which you might want to do since I believe the original certificate is only valid for 365 days.<br />
<br />
In the instructions below we will use the provided self-signed certificate (ssl-cert-snakeoil.pem and ssl-cert-snakeoil.key) but you can also generate your own using openssh following instructions on the web. As we said above, for a production server, you should really use an official certificate.<br />
<br />
====Set up Apache to use SSL====<br />
<br />
First we enable the <code>mod_ssl</code> module<br />
$ sudo a2enmod ssl<br />
[sudo] password for wwadmin: <wwadmin password><br />
<br />
Now we have to configure Apache to use SSL.<br />
$ cd /etc/apache2/sites-available/<br />
$ sudo cp default-ssl.conf default-ssl.conf.bak1<br />
[sudo] password for wwadmin: <wwadmin password><br />
$ sudo nano default-ssl.conf<br />
<br />
Our self-signed certificate and key files are named <br />
<code>ssl-cert-snakeoil.pem</code> and <code>ssl-cert-snakeoil.key</code>. If you<br />
are using official files, put their names in the lines below. You will also have to edit the Certificate Chain, Certificate Authority and possibly other items. Instructions for doing so are beyond the scope of this document. You might look at https://www.digitalocean.com/community/tutorials/how-to-secure-apache-with-let-s-encrypt-on-ubuntu-18-04<br />
<br />
Search for the lines<br />
SSLCertificateFile /etc/ssl/certs/ssl-cert-snakeoil.pem<br />
SSLCertificateKeyFile /etc/ssl/private/ssl-cert-snakeoil.key<br />
and replace <code>ssl-cert-snakeoil.pem</code> and <code>ssl-cert-snakeoil.key</code> by the names of your certificate. Since in these instructions we are using <br />
<code>ssl-cert-snakeoil.pem</code> and <code>ssl-cert-snakeoil.key</code>, we can just leave the lines as is.<br />
<br />
Then save the file and quit. And enable <code>default-ssl.conf</code> <br />
$ sudo a2ensite default-ssl.conf<br />
[sudo] password for wwadmin: <wwadmin password><br />
Finally we restart Apache<br />
$ sudo systemctl restart apache2<br />
and test things. Connect to https://yourserver.yourschool.edu/webwork2/myTestCourse<br />
You will be asked to accept the certificate. After you do so things should work just as before except that the connection will be via https except for images, MathJax, etc. if you using lighttp. In that case, viewing math expressions in image mode should work fine but it is possible using MathJax mode will fail. We will talk about this below.<br />
<br />
====Redirect http requests to https====<br />
Assuming that everything is working, the last thing we do is set things up so that requests to http://yourserver.yourschool.edu/webwork2/ are automatically redirected to https://yourserver.yourschool.edu/webwork2/.<br />
<br />
$ cd /etc/apache2/sites-available<br />
$ sudo cp 000-default.conf 000-default.conf.bak1<br />
[sudo] password for wwadmin: <wwadmin password><br />
$ sudo nano 000-default.conf<br />
<br />
In the <br />
<VirtualHost *:80><br />
section just under the line<br />
DocumentRoot /var/www/html<br />
add the line<br />
Redirect permanent /webwork2 https://yourserver.yourschool.edu/webwork2<br />
where of course you should edit <code>yourserver.yourschool.edu</code> appropriately.<br />
Then save the file and quit.<br />
Restart Apache<br />
$ sudo service apache2 restart<br />
and try connecting to http://yourserver.yourschool.edu/webwork2/. The real connection should be through https://yourserver.yourschool.edu/webwork2/.<br />
<br />
====Check site.conf====<br />
This is important. We have to check the value of $server_root_url in webwork2/conf/site.conf to make <br />
sure it uses https (so it should read e.g. https://yourserver.yourschool.edu). If<br />
you don't do this, your may run into strange problems in the Library Browser.<br />
To check, open the Library Browser, select a subject and then click on the chapter area. If you see a drop down list of chapters, things are working properly. <br />
<br />
Now we check and edit if necessary site.conf<br />
cd /opt/webwork/webwork2/conf<br />
nano site.conf<br />
<br />
In the line<br />
$server_root_url = ...<br />
replace http by https if necessary. Then save the file, quit and restart apache<br />
sudo service apache2 restart <br />
[sudo] password for wwadmin: <wwadmin password><br />
<br />
===Configure lighttpd to use SSL===<br />
<br />
We are using lighttpd for images, pdf's and MathJax (if MathJax is installed locally) MathJax may fail (so mathematical expressions will not be displayed) if it runs under lighttpd and you do not configure lighttpd to use SSL. So let's configure lighttpd to use SSL.<br />
<br />
For lighttpd you need to concatenate the key file and the certificate file into a single pem file by running the following command.<br />
Obviously you should use the real name of your certificate and key files, not "apache.key" and "apache.crt".<br />
<br />
$ sudo -s<br />
[sudo] password for wwadmin: <wwadmin password><br />
# cd /etc/ssl/private<br />
# cat apache.key ../certs/apache.crt > apache.pem<br />
# chmod 640 apache.pem<br />
# exit<br />
$<br />
<br />
If you are using official certificates,<br />
you will also have to edit the Certificate Chain, Certificate Authority and possibly other items. Instructions for doing so are beyond the scope of this document. See e.g.<br />
http://redmine.lighttpd.net/projects/lighttpd/wiki/Docs_SSL and/ or https://www.vultr.com/docs/setup-let-s-encrypt-with-lighttpd-on-ubuntu-16-04 <br />
<br />
<br />
Since we already are using the files <code>ssl-cert-snakeoil.pem</code> and <code>ssl-cert-snakeoil.key</code> for apache, we will also use them for lighttpd<br />
<br />
$ sudo cat /etc/ssl/private/ssl-cert-snakeoil.key /etc/ssl/certs/ssl-cert-snakeoil.pem >/etc/lighttpd/lighttpd.pem<br />
[sudo] password for wwadmin: <wwadmin password><br />
<br />
Now edit <code>lighttpd.conf</code>. <br />
$ cd /etc/lighttpd<br />
$ sudo cp lighttpd.conf lighttpd.conf.bak2<br />
[sudo] password for wwadmin: <wwadmin password><br />
$ sudo nano lighttpd.conf<br />
<br />
First in the list of <code>server.modules</code> at the top of the file, under the last module <code>"mod_setenv",</code>, add the module<br />
"mod_openssl",<br />
<br />
Next under the line<br />
server.port = 8080<br />
add the following<br />
$SERVER["socket"] == ":8443" {<br />
ssl.engine = "enable"<br />
ssl.pemfile = "/etc/lighttpd/lighttpd.pem"<br />
}<br />
<br />
Then save the file and quit.<br />
<br />
And restart lighttpd and check it's status<br />
<br />
$ sudo systemctl restart lighttpd<br />
[sudo] password for wwadmin: <wwadmin password><br />
$ sudo systemctl status lighttpd<br />
<br />
Sometimes when Lighttpd would not restart (or start) I just rebooted the server and everything worked. If you have difficulty you can run the command<br />
$ sudo lsof -i -P -n | grep LISTEN<br />
which will list all the ports your server is listening to. In the list you should see something similar to<br />
lighttpd 519 www-data 5u IPv4 18610 0t0 TCP *:8443 (LISTEN)<br />
<br />
<br />
====Edit localOverrides.conf</code>====<br />
$ cd /opt/webwork/webwork2/conf<br />
$ cp localOverrides.conf localOverrides.conf.bak4<br />
$ nano localOverrides.conf<br />
and replace all occurrences of 8080 by 8443 (one occurrence in three different lines). Then in these same three lines replace <code>http</code> by <code>https</code> . Obviously, you have to edit the three active lines and can ignore the commented out lines.<br />
<br />
Then save the file and quit. And restart apache<br />
$ sudo service apache2 restart<br />
[sudo] password for wwadmin: <wwadmin password><br />
<br />
and test that all is well by viewing a page with math expressions using MathJax mode.<br />
<br />
===Implement Optional D (Rserve)===<br />
<br />
Here we will install and configure the R server for statistical computing. Many statistics and probability problems (mostly contributed by faculty at the University of British Columbia) require this.<br />
<br />
See the documentation (from which we have borrowed heavily) [[R_in_WeBWorK]] for more detailed information.<br />
<br />
====Install the R server====<br />
$ sudo apt install r-cran-rserve<br />
[sudo] password for wwadmin: <wwadmin password><br />
<br />
and check that R is running<br />
$ R<br />
<br />
You should see something very similar to <br />
<br />
R version 3.6.3 (2020-02-29) -- "Holding the Windsock"<br />
Copyright (C) 2020 The R Foundation for Statistical Computing<br />
...<br />
Type 'q()' to quit R.<br />
<br />
><br />
and then quit<br />
> q()<br />
Save workspace image? [y/n/c]: n<br />
<br />
====Configure Webwork with the location of the R server====<br />
Edit the localOverrides.conf file<br />
<br />
$ cd /opt/webwork/webwork2/conf<br />
$ nano localOverrides.conf<br />
<br />
Search for the line<br />
$pg{specialPGEnvironmentVars}{DragMath}<br />
and under that line add the following<br />
<br />
################################################################################<br />
#location of the R server<br />
################################################################################<br />
$pg{specialPGEnvironmentVars}{Rserve} = {host => 'localhost'};<br />
<br />
Then save the file and Quit.<br />
<br />
====Set up Rserve to run as a daemon at system boot====<br />
<br />
This is somewhat complicated. I'm basically following instructions from https://github.com/geordielad/rserve-systemd-unit<br />
<br />
First we create a user with limited privileges to run rserve.<br />
<br />
$ sudo adduser rserveuser --system --shell=/bin/false --no-create-home --disabled-password --disabled-login<br />
<br />
<br />
Next we create a file to automatically start Rserve<br />
<br />
$ cd<br />
$ nano rserve.service<br />
Now copy and paste the following code into nano<br />
<br />
[Unit]<br />
Description=Rserve<br />
<br />
[Service]<br />
Type=forking<br />
PIDFile=/var/run/rserve/rserve.pid<br />
<br />
# Define runtime directory<br />
RuntimeDirectory=rserve<br />
RuntimeDirectoryMode=750<br />
<br />
User=rserveuser<br />
Group=nogroup<br />
<br />
ExecStart=/usr/bin/R CMD Rserve --quiet --vanilla --RS-pidfile /var/run/rserve/rserve.pid<br />
<br />
[Install]<br />
WantedBy=multi-user.target<br />
<br />
and then save the file and quit.<br />
Change the owner to root, move the file to the proper location and register it.<br />
<br />
$ sudo chown root:root rserve.service<br />
[sudo] password for wwadmin: <wwadmin password><br />
$ sudo mv rserve.service /etc/systemd/system<br />
$ sudo systemctl daemon-reload<br />
<br />
Finally we enable the service to start when the system starts<br />
<br />
$ sudo systemctl enable rserve.service<br />
<br />
====Test that things are working properly====<br />
<br />
First start Rserve manually<br />
$ sudo systemctl start rserve<br />
[sudo] password for wwadmin: <wwadmin password><br />
and run <br />
$ sudo lsof -i -P -n | grep LISTEN<br />
and you should see that Rserve is listening on port 6311<br />
<br />
Next test that WeBWorK problems using R run properly. In WeBWorK, click on <code>Library Browser</code> on the <code>Main Menu</code>. Then click <code>Open Problem Library </code> (actually it should already be selected so it will be greyed out). <br />
Now 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 />
<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 />
Finally reboot your server (to test that the Rserve starts automatically on boot up) and run <br />
$ sudo systemctl status rserve.service<br />
[sudo] password for wwadmin: <wwadmin password><br />
to check that all is well and just to be redundant <br />
$ sudo lsof -i -P -n | grep LISTEN<br />
again. Now we are sure that Rserve automatically starts when the system is booted.<br />
<br />
====Loading additional modules====<br />
This step should not be necessary unless you are writing or using WeBWorK problems that need additional resources beyond what is loaded by default. An example is using R to compute complex eigenvalues which requires the <code>Math::Complex</code> module (see https://webwork.maa.org/moodle/mod/forum/discuss.php?d=5577). The error message in such a case would be similar to <br />
Can't locate object method "make" via package "Math::Complex" (perhaps you forgot to load "Math::Complex"?) at /usr/share/perl/5.30/Math/Complex.pm line 329<br />
Died within Math::Complex::cplx called at line 351 of /usr/local/share/perl/5.30.0/Statistics/R/IO/QapEncoding.pm<br />
from within Statistics::R::IO::QapEncoding::decode called at line 236 of /usr/local/share/perl/5.30.0/Statistics/R/IO/Rserve.pm<br />
from within Statistics::R::IO::Rserve::eval called at line 26 of [PG]/lib/Rserve.pm<br />
from within Rserve::try_eval called at line 146 of [PG]/macros/RserveClient.pl<br />
from within main::rserve_eval called at line 40 of (eval 4456)<br />
<br />
First note that the required module must be installed on your server (see [[#Installing Perl Modules|Installing Perl Modules]] above). The <code>Math::Complex</code> module already is.<br />
<br />
We need to load <code>Math::Complex</code> into WeBWorK's safe compartment. For this we have to edit the localOverrides.conf file.<br />
<br />
$ cd /opt/webwork/webwork2/conf<br />
$ nano localOverrides.conf<br />
Now search for the line<br />
# Additional PG modules<br />
and under the line<br />
#push (@{${pg}{modules}}, [qw(TikZ_Image2)]);<br />
add the lines<br />
push @{$pg{modules}},<br />
[qw( Math::Complex )],<br />
; <br />
You can add as many modules as you need this way.<br />
<br />
Then save the file and Quit.<br />
<br />
===Implement Optional E (Logrotate)===<br />
Here we will set up log rotation for WeBWorK's timing log which can grow huge especially if you have a large number of users. The <code>timing.log</code> gives timing information on every action in WeBWorK (see [[WeBWorK_performance]]) and can be used to assess the performance of your server.<br />
<br />
====Create a WeBWorK configuration file for Logrotate====<br />
Logrotate’s configuration files are located in <code>/etc/logrotate.d</code>. Now we create one for WeBWorK.<br />
<br />
$ sudo nano /etc/logrotate.d/webwork<br />
<br />
Now copy and paste the following code into nano<br />
/opt/webwork/webwork2/logs/timing.log {<br />
su www-data wwdata<br />
weekly<br />
missingok<br />
rotate 15<br />
compress<br />
delaycompress<br />
notifempty<br />
}<br />
and then save the file and quit. The backup will be done weekly and we are keeping 15 weeks (approximately one semester) worth of logs. <br />
The most recent backup will not be compressed but all older ones will be. We are not explicitly creating a new <code>timing.log</code> file <br />
because WeBWorK will automatically create one if it's missing. If you want to check that it works you can run <code>logrotate</code><br />
with the configuration file (make sure you have done something with WeBWorK so that the <code>timing.log</code> is not empty):<br />
<br />
sudo logrotate -f /etc/logrotate.d/webwork<br />
[sudo] password for wwadmin: <wwadmin password><br />
<br />
Then if you look in <code>/opt/webwork/webwork2/logs</code>, you should see<br />
<br />
timing.log.1<br />
<br />
You will not see a <code>timing.log</code> file unless someone has been doing something with WeBWorK. If there is no <code>timing.log</code> file<br />
do something yourself (e.g. login to a course) and then you should see <br />
<br />
timing.log<br />
timing.log.1<br />
<br />
Now run <code>logrotate</code> again <br />
sudo logrotate -f /etc/logrotate.d/webwork<br />
[sudo] password for wwadmin: <wwadmin password><br />
and do something in WeBWorK and you should see<br />
<br />
timing.log<br />
timing.log.1<br />
timing.log.2.gz<br />
<br />
Here is what is going on. <code>timing.log.1</code> was renamed to <code>timing.log.2</code> and compressed giving <code>timing.log.2.gz</code>. <code>timing.log</code> was renamed to <code>timing.log.1</code>. <br />
And the something you (or someone else) did in WeBWorK created a new <code>timing.log</code> file. A similar procedure will happen weekly until there are a total of <br />
15 backups after which the oldest one will be deleted.<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. <br />
<br />
To fix this 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", "HTML_tth", ],<br />
<br />
Then save the file and Quit.<br />
<br />
This may or may not be addressed in a WeBWorK 15 hotfix (see [[#Checking for and Installing Hotfixes|Checking for and Installing Hotfixes]]).<br />
<br />
===UTF-8 support===<br />
WW 2.15 has some "known issues" with the UTF-8 support that arise in some WeBWorK problems. These issues are discussed in a forum discussion at: <br />
https://webwork.maa.org/moodle/mod/forum/discuss.php?d=4795. The discussion there lists pull requests by <br />
Nathan Wallach and Davide Cervone that address these issues. If you write or use WeBWorK problems that have issues with UTF-8 characters,<br />
look at that discussion. Again these issues may or may not be addressed in a WeBWorK 15 hotfix (see [[#Checking for and Installing Hotfixes|Checking for and Installing Hotfixes]]).<br />
<br />
Systems using UTF-8 problems probably need to patch /usr/share/perl5/XMLRPC/Lite.pm as explained at https://github.com/openwebwork/webwork2/issues/967#issuecomment-523941959 and may want to consider the fixes accepted in the develop branch via https://github.com/openwebwork/webwork2/pull/1089 and https://github.com/openwebwork/pg/pull/466 .<br />
<br />
==Where to go From Here ==<br />
<br />
You should play around with <code>myTestCourse</code> e.g. click on <code>Library Browser</code> and browse the <code>Problem Library</code>.<br />
<br />
Look at [[A day in the life of a WeBWorK instructor]].<br />
<br />
Read [[Course Administration]] for more information about creating courses.<br />
<br />
Under Categories below click on Administrators to see a listing of other WeBWorK documentation for system administrators.<br />
<br />
-- Main.ArnoldPizer update by Peter Staab - 19 May 2021 <br /><br />
<br />
[[Category:Administrators]]<br />
[[Category:Installation Manuals]]</div>141.154.51.251https://webwork.maa.org/mediawiki_new/index.php?title=Installation_Manual_for_2.16_on_Ubuntu&diff=20950Installation Manual for 2.16 on Ubuntu2021-05-20T10:46:05Z<p>141.154.51.251: /* Apache2 Modules and mod perl */</p>
<hr />
<div><br />
{{UnderConstruction}}<br />
<br />
'''These instructions are a work in progress. '''<br />
<br />
<br />
These instructions cover the installation of WeBWorK 2.16 for Ubuntu Server 20.04 LTS. <br />
<br />
If you are just upgrading WeBWorK, especially if you already have existing WeBWorK courses, see [[Upgrading_WeBWorK_with_Github]].<br />
<br />
Also, it is assumed that you have Ubuntu Server 20.04 LTS installed. You can visit [[Installation_Manual_for_2.15_on_Ubuntu_20.04_Server]] for instructions on installing Ubuntu 20.04 LTS. Also make sure the OS is upgraded to all patches within the version you are running. <br />
<br />
== Notation ==<br />
<br />
First some short comments on notation we will be using. We will use <code>&lt;key&gt;</code> to indicate that you should press a specific key (e.g. <code>&lt;Enter&gt;</code>, <code>&lt;Tab&gt;</code>, <code>&lt;F12&gt;</code>, etc.). Sometimes we will also use e.g. <code>&lt;wwadmin password&gt;</code> to indicate you have to enter the wwadmin password.<br />
<br />
<code>^</code> will indicate the <code>&lt;Ctrl&gt;</code> key so e.g. <code>^X</code> is really shorthand for <code>&lt;Ctrl&gt; &lt;X&gt;</code>, i.e. press the Ctrl key and hit the X key.<br />
<br />
Code blocks that begin with <code>#</code> must be run with root privileges (via either a root shell or prefixing the command with <code>sudo</code>). You can enter a root shell with <code>sudo -s</code>. Code blocks that begin with <code>$</code> may be run as a standard user. You are not intended to type the <code>#</code> or <code>$</code> characters as part of the provided commands.<br />
<br />
==Install Software Packages==<br />
<br />
=== Ubuntu Software Packages ===<br />
<br />
On Ubuntu and other Debian linuxes, the following instructions will get needed software packages installed. <br />
<br />
Here is the list of Ubuntu packages that need to be installed. <br />
<br />
# <code>apache2</code><br />
# <code>cpanminus</code><br />
# <code>curl</code><br />
# <code>dvipng</code><br />
# <code>dvisvgm</code><br />
# <code>gcc</code><br />
# <code>git</code><br />
# <code>imagemagick</code><br />
# <code>libapache2-request-perl</code><br />
# <code>libarchive-zip-perl</code><br />
# <code>libarray-utils-perl</code><br />
# <code>libcrypt-ssleay-perl</code><br />
# <code>libdancer-perl</code><br />
# <code>libdancer-plugin-database-perl</code><br />
# <code>libdata-dump-perl</code><br />
# <code>libdatetime-perl</code><br />
# <code>libemail-address-xs-perl</code><br />
# <code>libemail-sender-perl</code><br />
# <code>libexception-class-perl</code><br />
# <code>libextutils-xsbuilder-perl</code><br />
# <code>libfile-find-rule-perl-perl</code><br />
# <code>libgd-perl</code><br />
# <code>libhtml-scrubber-perl</code><br />
# <code>libhttp-async-perl</code><br />
# <code>libiterator-perl</code><br />
# <code>libiterator-util-perl</code><br />
# <code>libjson-perl</code><br />
# <code>liblocale-maketext-lexicon-perl</code><br />
# <code>libmime-tools-perl</code><br />
# <code>libmoox-options-perl</code><br />
# <code>libnet-ip-perl</code><br />
# <code>libnet-ldap-perl</code><br />
# <code>libnet-oauth-perl</code><br />
# <code>libossp-uuid-perl</code><br />
# <code>libpadwalker-perl</code><br />
# <code>libpath-class-perl</code><br />
# <code>libphp-serialization-perl</code><br />
# <code>libpod-wsdl-perl</code><br />
# <code>libsoap-lite-perl</code><br />
# <code>libsql-abstract-perl</code><br />
# <code>libstring-shellquote-perl</code><br />
# <code>libtemplate-perl</code><br />
# <code>libtext-csv-perl</code><br />
# <code>libtimedate-perl</code><br />
# <code>libuuid-tiny-perl</code><br />
# <code>libxml-parser-easytree-perl</code><br />
# <code>libxml-parser-perl</code><br />
# <code>libxml-writer-perl</code><br />
# <code>make</code><br />
# <code>netpbm</code><br />
# <code>npm</code><br />
# <code>openssh-server</code><br />
# <code>pdf2svg</code><br />
# <code>preview-latex-style</code><br />
# <code>texlive</code><br />
# <code>texlive-latex-extra</code><br />
# <code>unzip</code><br />
<br />
<br />
'''To install all of these packages in one fell swoop''' run the command ('''obviously you want to use cut and paste''')<br />
<br />
$ sudo apt install apache2 cpanminus curl dvipng dvisvgm gcc git imagemagick libapache2-request-perl \<br />
libarchive-zip-perl libarray-utils-perl libcrypt-ssleay-perl libdancer-perl \<br />
libdancer-plugin-database-perl libdata-dump-perl libdatetime-perl libemail-address-xs-perl \<br />
libemail-sender-perl libexception-class-perl libextutils-xsbuilder-perl \<br />
libfile-find-rule-perl-perl libgd-perl libhtml-scrubber-perl libhttp-async-perl \<br />
libiterator-perl libiterator-util-perl libjson-perl liblocale-maketext-lexicon-perl \<br />
libmime-tools-perl libmoox-options-perl libnet-ip-perl libnet-ldap-perl libnet-oauth-perl \<br />
libossp-uuid-perl libpadwalker-perl libpath-class-perl libphp-serialization-perl \<br />
libpod-wsdl-perl libsoap-lite-perl libsql-abstract-perl libstring-shellquote-perl \<br />
libtemplate-perl libtext-csv-perl libtimedate-perl libuuid-tiny-perl \<br />
libxml-parser-easytree-perl libxml-parser-perl libxml-writer-perl make netpbm npm \<br />
openssh-server pdf2svg preview-latex-style texlive texlive-latex-extra unzip<br />
<br />
Enter the password for wwadmin at the prompt:<br />
<br />
[sudo] password for wwadmin: <wwadmin password><br />
<br />
Accept any prompts with the default answer by hitting <code>&lt;Enter&gt;</code>.<br />
<br />
=== Installation of Other Perl Modules with cpanm ===<br />
<br />
We will use <code>cpanm</code> to install other perl modules. For example, one module, <code>Statistics::R::IO</code> that will be needed is not in a standard package. To install this<br />
<br />
$ sudo cpanm Statistics::R::IO<br />
[sudo] password for wwadmin: <wwadmin password><br />
<br />
Below, we will determine other perl modules that will need to be installed with this method.<br />
<br />
== Setting up Apache2 ==<br />
<br />
This sets up some helpful modules for apache and tests to make sure that apache is up and running.<br />
<br />
=== enabling info.conf and status.conf in Ubuntu ===<br />
<br />
We enable the info module. Acting as <code>root</code> in a terminal window enter<br />
$ sudo -s<br />
[sudo] password for wwadmin: <wwadmin password><br />
# a2enmod info<br />
<br />
Next we make a copy of the configuration files we will be editing for safekeeping. <br />
<br />
# cd /etc/apache2/mods-available<br />
<br />
# cp info.conf info.conf.bak1<br />
# cp status.conf status.conf.bak1<br />
<br />
# exit<br />
$<br />
<br />
Now we will edit configuration files <code>info.conf</code> and <code>status.conf</code> to allow us to view information about the setup and performance of the web server. Note that this is not absolutely necessary but it can be very useful. You can use your favorite editor but we will give instructions assuming you are using <code>nano</code>. Note that you have to be root to edit these files. First we edit <code>info.conf</code><br />
<br />
$ cd /etc/apache2/mods-available<br />
$ sudo nano info.conf<br />
[sudo] password for wwadmin: <wwadmin password><br />
<br />
I suggest you allow access to server information from e.g. your department domain. To do this uncomment (i.e. remove the <code>#</code> from) <br />
Require ip 192.0.2.0/24<br />
and then replace <code>192.0.2.0/24</code> by <code>.math.yourschool.edu</code><br />
where of course you should edit <code>.math.yourschool.edu</code> appropriately. <br />
<br />
Then save the file and quit (press <code>^X</code>, <code>Y</code>, <code>&lt;Enter&gt;</code>).<br />
<br />
Now we edit <code>status.conf</code><br />
<br />
$ cd /etc/apache2/mods-available<br />
$ sudo nano status.conf<br />
[sudo] password for wwadmin: <wwadmin password><br />
<br />
Edit the <br />
#Require ip 192.0.2.0/24<br />
line just as you did for <code>info.conf</code>.<br />
Then save the file and quit. And restart Apache so that the above changes take effect<br />
<br />
$ sudo systemctl restart apache2<br />
password:<wwadmin password><br />
<br />
===Fully Qualified Domain Name=== <br />
Now we have to set your server's fully qualified domain name. Note that if your network was set up automatically via DHCP, your server's fully qualified domain name should already be set up. You can check by running the <code>hostname</code> commands below.<br />
<br />
Run the command <br />
sudo hostnamectl set-hostname webwork<br />
[sudo] password for wwadmin: <wwadmin password><br />
where of course you should replace webwork by whatever your server's name is.<br />
<br />
<br />
You can check these settings by running the commands<br />
<br />
$ hostname --fqdn<br />
and <br />
$ hostname<br />
<br />
The first gives the server's fully qualified domain name (e.g. webwork.mydepartment.myschool.edu) and the second the server's name (e.g. webwork).<br />
<br />
Note that if your server can not find its fully qualified domain name, certain tools (such as the Synaptic Package Manager) may not start.<br />
<br />
===Test Apache===<br />
Now restart Apache<br />
<br />
$ sudo systemctl restart apache2<br />
password:<wwadmin password><br />
or<br />
$ sudo apache2ctl restart<br />
[sudo] password for wwadmin: <wwadmin password><br />
or<br />
$ sudo service apache2 restart<br />
[sudo] password for wwadmin: <wwadmin password><br />
<br />
<br />
and test your server by connecting to your<br />
server ("http://yourserver.yourschool.edu") from a browser on a remote machine. You should see the '''Apache2 Ubuntu Default Page''' indicating that Apache is running.<br />
<br />
You can check Apache's status by connecting to<br />
"http://yourserver.yourschool.edu/server-status" from a browser on a remote machine in the math.yourschool.edu domain.<br />
<br />
Further test Apache by connecting to<br />
"http://yourserver.yourschool.edu/server-info" from a browser on a remote machine in the math.yourschool.edu domain and you will see a page listing various <br />
information about Apache. In particular under <code>Server Settings</code> you should see<br />
<br />
Server Version: Apache/2.4.41 (Ubuntu) mod_apreq2-20090110/2.8.0 mod_perl/2.0.11 Perl/v5.30.0<br />
(or something very similar) indicating that both <code>mod_apreq2</code> and <code>mod_perl</code> are installed.<br />
<br />
If you have problems now or in the future, a good first thing to do is to look at the Apache error log which is located at <code>/var/log/apache2/error.log</code>. In the directory <code>/var/log/apache2/</code> you can "less" through the error log (<code>less error.log</code>), look at the last few entries (<code>tail error.log</code>) or run the command <code>tail -f error.log</code> which will display new error messages as they are appended to the file. Use <br />
<code>^C</code> to break out of <code>tail -f</code> . For example if you didn't set up access to "server-info", you can run<br />
tail /var/log/apache2/error.log<br />
and in the output you should see something similar to<br />
...[mpm_event:notice] [pid 48932:tid 140494759132224] AH00489: Apache/2.4.41 (Ubuntu) mod_apreq2-20090110/2.8.0 mod_perl/2.0.11 Perl/v5.30.0 configured -- resuming normal operations<br />
indicating that both <code>mod_apreq2</code> and <code>mod_perl</code> are installed and running.<br />
<br />
== Installing a Database ==<br />
<br />
This section installs either MySQL or MariaDB as the database manger for webwork. It is recommended that MariaDB is used. There have been a few examples of connection issues with MySQL. <br />
<br />
<br />
=== Installing and Testing MariaDB ===<br />
<br />
Install MariaDB using the distro packages. <br />
<br />
$ sudo apt install mariadb-server libdbd-mariadb-perl<br />
<br />
<br />
=== Installing and Testing MySQL ===<br />
<br />
If you wish to use MySQL: <br />
<br />
$ sudo apt install mysql-server libdbd-mysql-perl<br />
<br />
=== Securing the Database ===<br />
<br />
Then we should secure the server<br />
<br />
$ sudo mysql_secure_installation<br />
[sudo] password for wwadmin: <wwadmin password><br />
<br />
You can setup the VALIDATE PASSWORD plugin if you wish. I chose not to.<br />
<br />
Next you will be asked to enter a<br />
<code>New password for the MySQL "root" user</code>. Enter your chosen MySQL <code>root</code> password. You have to enter a password but it will not be used. In Ubuntu systems running MySQL 5.7 (and later versions), the root MySQL user is set to authenticate using the auth_socket plugin by default rather than with a password. <br />
<br />
You almost certainly want to answer 'Y' to all questions '''except''' possibly for the first one which asks if you want to set up a VALIDATE PASSWORD plugin.<br />
Now test that all is well:<br />
<br />
$ sudo mysql <br />
[sudo] password for wwadmin: <wwadmin password><br />
<br />
You should see<br />
<br />
Welcome to the MySQL monitor ...<br />
mysql><br />
<br />
Now lets check the MySQL users.<br />
There are five accounts. To see the accounts, do the following <br />
<br />
mysql> SELECT user,authentication_string,plugin,host FROM mysql.user;<br />
<br />
You will see a table with five users (<code>debian-sys-maint</code>, <code>mysql.infoschema</code>, <code>mysql.session</code>, <code>mysql.sys</code> and <code>root</code>). <br />
You should see that one of the five users has a valid password (which will be displayed in encrypted form) and <code>root</code> is authenticated by a socket. You can ignore the <code>mysql.session</code>, <code>mysql.sys</code> and <code>mysql.infoschema</code> users.<br />
<br />
Now exit MySQL<br />
<br />
mysql> exit<br />
Bye<br />
$<br />
<br />
This last step is optional since currently most of WeBWorK's MySQL tables are now created using the MyISAM engine (by default -- this can be changed in the config files) rather than the MySQL default engine. Now we change MySQL's default engine. The default engine is InnoDB as of MySQL 5.5.5 (MyISAM before 5.5.5) but (at least on some hardware) InnoDB seems to be 50-100 times slower than MyISAM. So we will change the default MySQL engine from InnoDB to MyISAM. Note that this change only applies to new tables, tables already constructed will continue to use InnoDB. But we haven't created any WeBWorK tables so we don't have to change the engine for any existing tables.<br />
<br />
=== Changing the default MySQL/MariaDB engine ===<br />
<br />
To change the default MySQL engine from InnoDB to MyISAM do the following:<br />
<br />
$ cd /etc/mysql/mysql.conf.d<br />
$ sudo cp mysqld.cnf mysqld.cnf.bak1<br />
[sudo] password for wwadmin: <wwadmin password><br />
$ sudo nano mysqld.cnf<br />
<br />
If MariaDB is used instead of MySQL then edit the file <code>/etc/mysql/mariadb.conf.d/50-server.cnf</code>, instead of <code>/etc/mysql/mysql.conf.d/mysqld.cnf</code>.<br />
<br />
Search for <code>[mysqld]</code> and under "Basic Settings" above the "user = mysql" line add the line<br />
default-storage-engine = myisam<br />
<br />
Then save the file and quit. Restart MySQL.<br />
<br />
$ sudo systemctl restart mysql<br />
[sudo] password for wwadmin: <wwadmin password><br />
or<br />
$ sudo service mysql restart<br />
[sudo] password for wwadmin: <wwadmin password><br />
<br />
and log into mysql<br />
$ sudo mysql <br />
[sudo] password for wwadmin: <wwadmin password><br />
<br />
You will see<br />
<br />
Welcome to the MySQL monitor ...<br />
mysql><br />
<br />
If you show MySQL engines<br />
<br />
mysql> SHOW ENGINES\G<br />
<br />
you should see that MyISAM is listed as the default engine:<br />
...<br />
*************************** 5. row ***************************<br />
Engine: MyISAM<br />
Support: DEFAULT<br />
Comment: MyISAM storage engine <br />
Transactions: NO<br />
XA: NO<br />
Savepoints: NO<br />
<br />
Now exit<br />
mysql> exit<br />
Bye<br />
$<br />
<br />
== Downloading the WeBWorK System Software and Problem Libraries ==<br />
We are finally at the point where we can start downloading and installing WeBWorK. We will use Git to download WeBWorK from Github. This is easy and it will also make it easy to update the system in the future. Note that the following are rather long commands; it is much easier to copy (<code>^C</code>) them from this document and paste (<code>&lt;Shift&gt; &lt;Ctrl&gt; &lt;V&gt;</code><br />
or <code>&lt;Shift&gt; &lt;Insert&gt;</code>) them in a terminal window<br />
<br />
$ cd<br />
$ cd downloads<br />
$ git clone git://github.com/openwebwork/webwork2.git<br />
$ git clone git://github.com/openwebwork/pg.git<br />
$ git clone git://github.com/openwebwork/webwork-open-problem-library.git<br />
<br />
'''Important Note'''. The above commands retrieve the master branch which gives the latest stable release of the software package (webwork2, pg, etc.) with bug fixes. If a stable release newer than 2.15 exists, that will be downloaded and these instructions may be a little out of date. So it is a good idea to check before downloading. The best way to do that is to look at https://github.com/openwebwork/webwork2/blob/master/VERSION and https://github.com/openwebwork/pg/blob/master/VERSION.<br />
<br />
The first and second download gives you the latest released versions.<br />
The third download contains the WeBWorK Open Problem Library (OPL) which is the new name for the original National Problem Library (NPL). The NPL has been renamed to reflect its growing international content. Your system will be loaded with many thousands of WeBWorK problems (over 30,000 currently).<br />
<br />
The main information page about WebWork downloads is available at http://webwork.maa.org/wiki/Category:Release_Notes<br />
<br />
The main information page about the OPL is available at http://webwork.maa.org/wiki/Open_Problem_Library<br />
<br />
==Installing WeBWorK==<br />
<br />
'''Note the instructions below assume you are installing WeBWorK from scratch. If you are just upgrading WeBWorK, especially if you already have existing WeBWorK courses, see [[Upgrading WeBWorK]].'''<br />
<br />
=== Move the System into the Required Directories ===<br />
As <code>root</code> create a <code>webwork</code> directory under <code>/opt</code>, change the ownership of the <code>webwork</code> directory to <code>www-data</code>, which is what the apache server runs as and move directories there. <br />
<br />
$ cd<br />
$ cd downloads<br />
$ sudo mkdir /opt/webwork<br />
[sudo] password for wwadmin: <wwadmin password><br />
$ sudo chown www-data:www-data /opt/webwork<br />
$ sudo mv webwork2 /opt/webwork/<br />
$ sudo mv pg /opt/webwork/<br />
<br />
<br />
<br />
Now create the <code>courses</code> and <code>libraries</code> directories under <code>webwork</code> and copy and move content there <br />
<br />
$ sudo mkdir /opt/webwork/courses<br />
$ sudo mkdir /opt/webwork/libraries<br />
$ sudo mv webwork-open-problem-library /opt/webwork/libraries/<br />
$ cd /opt/webwork/webwork2/courses.dist<br />
$ sudo cp *.lst /opt/webwork/courses/<br />
$ sudo rsync -a modelCourse /opt/webwork/courses/<br />
<br />
=== Setting Permissions ===<br />
<br />
The PG installation directory and files should be owned by <code>www-data</code> and not writable by other users:<br />
<br />
$ cd /opt/webwork/pg<br />
$ sudo chmod -R u+rwX,go+rX .<br />
<br />
Most WeBWorK directories and files should also be owned by <code>www-data</code> and not writable by other users:<br />
<br />
$ cd /opt/webwork/webwork2<br />
$ sudo chmod -R u+rwX,go+rX .<br />
<br />
Certain data directories need to be writable by the web server. These are <code>DATA</code>, <code>courses</code>, <code>htdocs/tmp</code>, <code>logs</code>, and <code>tmp</code>. It is convenient to give WeBWorK administrators access to these directories as well, so they can perform administrative tasks such as removing temporary files, creating and editing courses from the command line, managing logs, and so on. We will use the group <code>www-data</code>, containing both the WeBWorK administrators and the web server. Consider the user WWADMIN<br />
<br />
Run the command:<br />
$ sudo adduser wwadmin www-data<br />
<br />
$ id wwadmin<br />
<br />
and then you should see <code>wwdata</code> listed under groups. Also<br />
<br />
$ id www-data<br />
<br />
should show <code>www-data</code> listed under groups. <br />
<br />
Now we make the WeBWorK directories that need to be writable by the web server have <code>www-data</code> as their group. The following are rather long commands; you might want to copy them and paste them into your terminal window rather than typing them.<br />
<br />
$ sudo -s<br />
[sudo] password for wwadmin: <wwadmin password><br />
# cd /opt/webwork/webwork2/<br />
# chgrp -R www-data DATA ../courses htdocs/tmp htdocs/applets logs tmp /opt/webwork/pg/lib/chromatic<br />
# chmod -R g+w DATA ../courses htdocs/tmp htdocs/applets logs tmp /opt/webwork/pg/lib/chromatic<br />
# find DATA/ ../courses/ htdocs/tmp logs/ tmp/ -type d -a -exec chmod g+s {} \;<br />
# exit<br />
$<br />
<br />
=== Compile color.c ===<br />
<br />
$ cd /opt/webwork/pg/lib/chromatic<br />
$ gcc color.c -o color<br />
<br />
You may see some warning messages which you can safely ignore.<br />
<br />
== Configuring the Shell ==<br />
<br />
To make working with WeBWorK easier, there are a couple of changes you can make to your shell environment.<br />
<br />
Add the WeBWorK <code>bin</code> directory to your path. This will allow you to run WeBWorK command-line utilities without typing the full path to the utility. Goto your home directory and backup your <code>.bashrc</code> file<br />
<br />
$ cd<br />
$ cp .bashrc .bashrc.bak1<br />
<br />
Now edit <code>.bashrc</code><br />
<br />
$ nano .bashrc<br />
<br />
After the last line add the three lines:<br />
<br />
export PATH=$PATH:/opt/webwork/webwork2/bin<br />
export WEBWORK_ROOT=/opt/webwork/webwork2<br />
export PG_ROOT=/opt/webwork/pg<br />
<br />
Then save the file and Quit.<br />
<br />
Close your Terminal Window and open a new one so the above changes<br />
take effect. You can check that they have by<br />
<br />
$ echo $PATH<br />
$ echo $WEBWORK_ROOT<br />
$ echo $PG_ROOT<br />
<br />
== Checking Module Dependencies ==<br />
<br />
WeBWorK includes a script called <code>check_modules.pl</code> (in the directory <code>/opt/webwork/webwork2/bin</code>) that verifies that the needed programs and Perl modules are installed on your system. Run this script to make sure you have installed the required programs and Perl modules.<br />
<br />
$ check_modules.pl apache2<br />
<br />
Scroll up and look through the listing. It should find everything. If something is missing (flagged by <code>**</code>), look back through these instructions to find where it should have been installed and install it. <br />
<br />
You may see some warning messages like <br />
Prototype mismatch: sub main::from_json: none vs ($@) at (eval 188) line 2.<br />
Prototype mismatch: sub main::to_json: none vs ($@) at (eval 188) line 2.<br />
This is a known bug in libjson-perl and can be safely ignored.<br />
<br />
A common perl package that isn't installed is <code>Statistics::R::IO</code>. It can be installed with<br />
<br />
$ sudo cpanm Statistics::R::IO<br />
<br />
which will install any needed dependencies and run tests. <br />
<br />
=== Obtaining Javascript Libraries ===<br />
<br />
Javascript libraries are now obtained using <code>npm</code>. This includes the following javascript packages:<br />
<br />
# <code>codemirror</code><br />
# <code>fontawesome</code><br />
# <code>iframe-resizer</code><br />
# <code>jQuery</code><br />
# <code>jQuery-ui</code><br />
# <code>MathJax</code><br />
# <code>nestedSortable</code><br />
<br />
To install all of these: <br />
<br />
$ cd /opt/webwork/webwork2/htdocs/<br />
$ npm install<br />
<br />
=== Checking LaTeX packages ===<br />
<br />
Now we check that all necessary LaTeX packages have been installed. Run the commands<br />
$ cd<br />
$ pdflatex /opt/webwork/webwork2/bin/check_latex.tex<br />
and look for missing packages (you can ignore "No file check_latex.aux.").<br />
<br />
=== Miscillaneous System Patches ===<br />
<br />
There is a bug in the Perl XMLRPC::Lite package that occurs with UTF8 characters. This can be fixed by applying the following patch:<br />
<br />
$ sudo patch -p1 -d / < /opt/webwork/webwork2/docker-config/xmlrpc-lite-utf8-fix.patch<br />
<br />
If the users of your system will be using problems that utilize the new <code>PGtikz.pl</code> macro then you will need to apply the following patch:<br />
<br />
$ sudo patch -p1 -d / < /opt/webwork/webwork2/docker-config/imagemagick-allow-pdf-read.patch<br />
<br />
== Configuring WeBWorK ==<br />
<br />
=== Making Copies of the Distribution Configuration Files ===<br />
<br />
Before configuring the system, you must make local copies of the <code>site.conf</code> and <code>localOverrides.conf</code> configuration files, located in <code>/opt/webwork/webwork2/conf/</code> . <br />
<br />
$ cd /opt/webwork/webwork2/conf<br />
$ sudo cp site.conf.dist site.conf<br />
$ sudo cp localOverrides.conf.dist localOverrides.conf<br />
<br />
=== WeBWorK System 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 instructors 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 />
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 />
==== Edit the site.conf file ====<br />
Now edit <code>site.conf</code><br />
<br />
$ sudo nano /opt/webwork/webwork2/conf/site.conf<br />
<br />
First we have to add information about the Apache2 server setup. <br />
Search for <code>server_root_url</code> and edit the line so that it reads:<br />
<br />
$server_root_url = 'http://yourserver.yourschool.edu';<br />
<br />
where of course you should edit <code>yourserver.yourschool.edu</code> appropriately. The "http://" is important. '''If you are running a secure server (i.e., using SSL - really TLS), the url should start with https:<br />
but you should wait to make that change until after WeBWorK is up and running and you set up SSL. In that case the "https://" is important.<br />
<br />
==== Database Settings ====<br />
<br />
Search for the code <code>$database_driver</code>. Uncomment the type of database you set up (MySQL or MariaDB) and comment out the other. <br />
<br />
We need to set a password that WeBWorK uses when it communicates with the MySQL database. Note that this is not the same as the <code>&lt;mysql root password&gt;</code> which is the unused password we set when securing MySQL.<br />
Search for <code>database_password</code> and replace the line<br />
$database_password = "passwordRW";<br />
by <br />
$database_password = 'database_password';<br />
where of course you should replace "database_password" with your own password but do use the single quotes. Remember this password as we will need it below.<br />
<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 />
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 />
'''Note:''' Some servers will need to set a value of <code>$server_apache_version</code> in <code>site.conf</code>. This setting is needed when the Apache settings disable the display of the Apache version number in Apache banner of the HTTP headers, typically by setting <code>ServerTokens Prod</code> in the Apache cponfig, as many security teams will recommend. In such cases, without a setting for this variable, WeBWorK will fail to detect that you are using Apache 2.4 and users will run into error pages reporting <code>Can't locate object method "remote_addr" via package "Apache2::Connection" at /opt/webwork/webwork2/lib/WeBWorK/Authen.pm</code> which will also appear in the Apache error.log file. The fix is to search for <code>$server_apache_version</code>, uncomment the line, and set a suitable value (currently "2.4" should work, and a fix to support settings like "2.4.29" is pending).<br />
<br />
Then save the file and Quit.<br />
<br />
==== Default Header Files ====<br />
<br />
After you have used WeBWorK for awhile, you may want to change the default header files in <code>defaults.config</code>. Search for <code>$webworkFiles{screenSnippets}{setHeader}</code> and <code>$webworkFiles{hardcopySnippets}{setHeader}</code> in <code>localOverrides.config</code>. Settings in the conf and config files affect all WeBWorK courses. You can override any setting in these conf and config files for an individual course by putting the local setting in <code>course.conf</code>.<br />
<br />
=== Set up the webwork database ===<br />
<br />
WeBWorK uses a single database, called <code>webwork</code>, for all courses. We will create the <code>webwork</code> database now.<br />
<br />
To do this do the following ('''before you just copy, paste and hit <code>&lt;Enter&gt;</code>''' notice that you have to replace <code>database_password</code> with the password you set when editing <code>site.conf</code> above):<br />
<br />
$ sudo mysql <br />
[sudo] password for wwadmin: <wwadmin password><br />
<br />
mysql> CREATE DATABASE webwork;<br />
mysql> CREATE USER 'webworkWrite'@'localhost' IDENTIFIED BY 'database_password';<br />
mysql> GRANT SELECT, INSERT, UPDATE, DELETE, CREATE, ALTER, DROP, LOCK TABLES ON webwork.* TO 'webworkWrite'@'localhost';<br />
mysql> exit<br />
Bye<br />
$ <br />
<br />
where as we said '''replace''' <code>database_password</code> with the password you set when editing <code>site.conf</code> above.<br />
<br />
=== Configuring Apache ===<br />
WeBWorK ships with an Apache config file that needs to linked into your Apache configuration process. The file is named <code>webwork.apache2.4-config.dist</code> and located in the <code>conf</code> directory. First, copy the file to <code>webwork.apache2-config</code>:<br />
<br />
$ cd /opt/webwork/webwork2/conf<br />
$ sudo cp webwork.apache2.4-config.dist webwork.apache2.4-config<br />
<br />
and now link it into your Apache configuration process<br />
<br />
$ sudo ln -s /opt/webwork/webwork2/conf/webwork.apache2.4-config /etc/apache2/conf-enabled/webwork.conf<br />
<br />
The default multi-processing module (MPM) for Apache is the event module but WeBWorK uses the prefork module. So we disable the event module and enable the prefork module.<br />
<br />
$ sudo a2dismod mpm_event<br />
$ sudo a2enmod mpm_prefork<br />
<br />
Next we will make a few changes to Apache's default configuration. We need to edit two files. First we will<br />
save copies of the original files. <br />
$ sudo -s<br />
# cd /etc/apache2/<br />
# cp apache2.conf apache2.conf.bak1<br />
# cd /etc/apache2/mods-available/<br />
# cp mpm_prefork.conf mpm_prefork.conf.bak1<br />
# exit<br />
<br />
====Edit apache2.conf====<br />
<br />
$ sudo nano /etc/apache2/apache2.conf<br />
<br />
Search for the line<br />
Timeout 300<br />
and replace it by<br />
Timeout 1200 <br />
<br />
Then save the file and quit. <br />
<br />
====Edit mpm_prefork.conf====<br />
<br />
$ cd /etc/apache2/mods-available/<br />
$ sudo nano mpm_prefork.conf<br />
<br />
Search for the lines<br />
MaxRequestWorkers 150<br />
MaxConnectionsPerChild 0<br />
Which occur under <code><IfModule mpm_prefork_module></code> and replace them by<br />
# For WeBWorK a rough rule of thumb is 5 MaxRequestWorkers per 1 GB of memory<br />
MaxRequestWorkers 10<br />
MaxConnectionsPerChild 50<br />
where you should set <code>MaxRequestWorkers</code> depending on the amount of memory your server has using the above rule of thumb. Note that for <br />
very busy servers, you should observe you memory usage and adjust the above settings as necessary. Also make sure MaxSpareServers is not set too high.<br />
<br />
Then save the file and quit.<br />
<br />
Finally we copy WeBWorK's icon file <code>favicon.ico</code> to Apache's <code>www</code> directory.<br />
$ sudo cp /opt/webwork/webwork2/htdocs/favicon.ico /var/www/html<br />
[sudo] password for wwadmin: <wwadmin password><br />
<br />
Now stop and start Apache. We do it this way to make sure the MPM gets changed. <br />
<br />
$ sudo apache2ctl stop<br />
[sudo] password for wwadmin: <wwadmin password><br />
$ sudo apache2ctl start<br />
<br />
== Test your configuration ==<br />
<br />
# Test the <code>/webwork2</code> location by visiting <code>http://yourserver.yourschool.edu/webwork2</code>. You should see the WeBWorK home page with no courses listed. Actually the directory <code>/opt/webwork/courses/</code> does contain the <code>modelCourse</code> but the <code>modelCourse</code> is not a real course so you will get an error message if you try to log into it. It will be used a as model for setting up other courses. For this reason <code>/opt/webwork/courses/modelCourse/</code> contains a file named <code>hide_directory</code> and so the <code>modelCourse</code> is not visible.<br />
# Test the <code>/webwork2_files</code> location by visiting <code>http://yourserver.yourschool.edu/webwork2_files</code>. You should see the "WeBWorK Placeholder Page".<br />
# You cannot test the <code>/webwork2_course_files</code> location until you have created a course.<br />
<br />
==If Something is Wrong ==<br />
If something is wrong one of the first things to check is that the config files have been edited correctly (e.g. one time a wrapped line in <code>localOverrides.conf</code> caused me problems, another time it was a missing single quote). A quick way to check this is to do a <code>diff</code> between the edited and distributed versions and check that <code>diff</code> reports the changes you made and only those. Another thing is to look at the Apache error log which is located at <code>/var/log/apache2/error.log</code>.<br />
<br />
$ cd /etc/apache2/<br />
$ diff apache2.conf apache2.conf.bak1<br />
$ cd /opt/webwork/webwork2/conf/<br />
$ diff site.conf site.conf.dist<br />
$ diff localOverrides.conf localOverrides.conf.dist<br />
$ diff webwork.apache2.4-config webwork.apache2.4-config.dist<br />
$ tail /var/log/apache2/error.log <br />
<br />
If something is wrong and you fix it, you will have to restart Apache for the changes to take effect<br />
<br />
$ sudo systemctl restart apache2<br />
[sudo] password for wwadmin: <wwadmin password><br />
<br />
== Create the admin Course ==<br />
<br />
[[Course Administration]] gives information about creating courses. Here we will give explicit instructions for doing this. (You may need to become root or use sudo to execute some of these commands.)<br />
<br />
$ cd /opt/webwork/courses<br />
$ /opt/webwork/webwork2/bin/addcourse admin --db-layout=sql_single --users=adminClasslist.lst --professors=admin<br />
$ sudo chown -R www-data:www-data admin <br />
[sudo] password for wwadmin: <wwadmin password><br />
<br />
where the last line makes the course <code>admin</code> and its subdirectories owned by the Apache server and readable/writeable by the WWADMIN user.<br />
<br />
Now goto <code>http://yourserver.yourschool.edu/webwork2</code> and should see the WeBWorK home page with <code>Course Administration</code> listed at the top. Click on it and login with Username <code>admin</code> and Password <code>admin</code> . This first thing you should do is register your new WeBWorK installation. It's quick and easy, just click on <code>Register</code>. '''IMPORTANT''' The next thing you should do is click on <code>User Settings</code> and change <code>admin</code> 's password to something more secure than <code>admin</code> . <br />
<br />
Unless you choose otherwise, users with <code>admin</code> privileges in the <code>admin</code> course (i.e. WeBWorK administrators) will automatically be added to new courses with <code>admin</code> privileges and the same password as in the <code>admin</code> course. Initially the only such user is <code>admin</code> (hopefully you are not confused by the fact that the course <code>admin</code> has a user named <code>admin</code>). It's usually convenient make yourself a WeBWorK administrator. To do this (assuming you are logged in as <code>admin</code> to the <code>admin</code> course at <code>http://yourserver.yourschool.edu/webwork2/admin</code> )<br />
# Click on <code>Classlist Editor</code> in the left panel<br />
# Click the <code>Add</code> tag and click <code>Take Action!</code><br />
# Enter the appropriate information (you can use your <code>Login Name</code> as the <code>Student ID</code> if you want and also you can leave the last three items blank) and click <code>Add Students</code><br />
# Click on <code>Classlist Editor</code> in the left panel again<br />
# When you enter a new student, by default their <code>Student ID</code> is used as their password. We'll change this now.<br />
# Select yourself with a check mark and click the <code>Password</code> tag and click <code>Take Action!</code>. (Note as a safely mechanism you can not change the password for the user you are logged in as, currently <code>admin</code>, this way) <br />
# Enter the password and then click <code>Take Action!</code><br />
# Finally give yourself <code>admin</code> privileges by selecting yourself with a check mark, clicking the <code>Edit</code> tag and then clicking <code>Take Action!</code> (or by just clicking on the "pencil" next to your login name which is a much faster way to edit classlist data for a single user)<br />
# Now at the far right change <code>Permission Level</code> from <code>student</code> to <code>admin</code><br />
# Then click <code>Take Action!</code><br />
<br />
At some point you will probably want to hide the <code>admin</code> course so that it is not listed on the WeBWorK home page. As we noted above the <code>modelCourse</code>, which is already hidden, is not a real course so you will get an error message if you try to log into it. This is a good reason to hide it. The <code>modelCourse</code> is very useful as a model (hence its name) for setting up other courses. The <code>admin</code> course is used for administering WeBWorK and even though regular users can not log into it (you did change the <code>admin</code> password, didn't you!!), it a little bit cleaner and safer to hide it from prying eyes. <br />
To hide (or unhide) a course select <code>Hide Inactive courses</code> in the admin course and follow the directions. When hidden a course will not show up in the courses list on the WeBWorK home page. It will still appear in the Course Administration listing. If you do this you will still be able to access the <code>admin</code> course using the URL <code>http://yourserver.yourschool.edu/webwork2/admin</code> but you will not see a link for it on the WeBWorK home page <code>http://yourserver.yourschool.edu/webwork2</code> . <br />
<br />
<br />
Now goto <code>http://yourserver.yourschool.edu/webwork2</code> and no course will be listed.<br />
<br />
==Checking for and Installing Hotfixes==<br />
<br />
The following commands show you how to check for and install bug fixes. '''Important Note:''' These commands check and retrieve the master branch which gives the latest stable release of the software package (webwork2, pg, etc.) with bug fixes. If a stable release newer than 2.15 exists for webwork2 and/or pg, that will be checked and retrieved which is probably not what you want. Please check before updating. The best way to do that is to look at https://github.com/openwebwork/webwork2/blob/master/VERSION and https://github.com/openwebwork/pg/blob/master/VERSION.<br />
<br />
To check if there are bug fixes, do the following. <br />
===Updating the webwork2 code===<br />
<br />
First we check for updates to the webwork2 code:<br />
cd /opt/webwork/webwork2/<br />
git remote show origin<br />
This will print several lines of data, but the last line will tell you if your copy is up to date or out of date. If it is out of date, run<br />
git pull origin and restart apache2.<br />
<br />
===Updating the pg code===<br />
<br />
Now check for updates to the pg code:<br />
cd /opt/webwork/pg/<br />
git remote show origin<br />
This will print several lines of data, but the last line will tell you if your copy is up to date or out of date. If it is out of date, run<br />
git pull origin<br />
and restart apache2.<br />
<br />
===Restart apache2===<br />
<br />
'''Important:''' After updating either webwork2 or pg, you have to restart apache2<br />
$ sudo apache2ctl restart<br />
password:<wwadmin password><br />
<br />
===Updating the OPL===<br />
<br />
The following assumes you have already installed the OPL. For that see [[#Install the Open Problem Library]] below.<br />
Now check for updates to the Open Problem Library:<br />
cd /opt/webwork/libraries/webwork-open-problem-library<br />
git remote show origin<br />
This will print several lines of data, but the last line will tell you if your copy is up to date or out of date. If it is out of date, run<br />
git pull origin<br />
Then rerun the <code>OPL-update</code> script. Updating the OPL is pretty much risk free since changes usually involve only a relatively small <br />
number of individual problems and the vast majority of problems remain unchanged. Updating the OPL does not require restarting apache2.<br />
<br />
$ OPL-update<br />
<br />
== Starting and Stopping Apache and MySQL ==<br />
If you make changes to the system, you will have to restart <code>apache2</code> before the changes take effect. On rare occasions you may need to restart <code>MySQL</code>. <br />
=== Starting and Stopping Apache ===<br />
You have to run these commands as <code>root</code>.<br />
<br />
To start or restart (i.e. stop and then start) the <code>apache2</code> webserver run the command <br />
$ sudo apache2ctl graceful<br />
[sudo] password for wwadmin: <wwadmin password><br />
You can also start <code>apache2</code> by<br />
$ sudo apache2ctl start<br />
[sudo] password for wwadmin: <wwadmin password><br />
and restart it with<br />
$ sudo apache2ctl restart<br />
[sudo] password for wwadmin: <wwadmin password><br />
<code>restart</code> is less graceful but more powerful than <code>graceful</code>. Sometimes <code>graceful</code> fails to kill all <code>apache2</code> child processes. <br />
<br />
<br />
To stop the Apache webserver run the command <br />
<br />
$ sudo apache2ctl stop<br />
[sudo] password for wwadmin: <wwadmin password><br />
<br />
Stopping and then starting Apache should definitely kill all <code>apache2</code> child processes. <br />
<br />
You can also start or stop apache2 by using the <code>apache2</code> service. Run<br />
$ sudo service apache2<br />
[sudo] password for wwadmin: <wwadmin password><br />
<br />
and you will get a list of allowed commands (<code>start</code>, <code>stop</code>, <code>restart</code>, etc.).<br />
<br />
Finally you can use the newer <code>systemctl</code> method, e.g.<br />
sudo systemctl start apache2<br />
[sudo] password for wwadmin: <wwadmin password><br />
<br />
sudo systemctl --help <br />
will give you a list of all possible commands, the main ones being <code>start</code>, <code>stop</code>, <code>restart</code> and <code>status</code>.<br />
<br />
Note that <code>systemctl</code> is the preferred method on modern versions of Ubuntu.<br />
<br />
=== Starting and Stopping MySQL or MariaDB ===<br />
You have to run these commands as <code>root</code>.<br />
<br />
To start the <code>MySQL</code> server run the command <br />
$ sudo systemctl start mysql<br />
<br />
To stop the <code>MySQL</code> server run the command <br />
$ sudo systemctl stop mysql<br />
<br />
To restart the <code>MySQL</code> server run the command <br />
$ sudo systemctl restart mysql<br />
<br />
To obtain more information about the mysql server run<br />
$ systemctl status mysql <br />
<br />
To get a list of all possible commands run <br />
$ systemctl --help<br />
<br />
==Install the WeBWorK Problem Libraries ==<br />
Before we create a real course we will install the WeBWorK Problem Libraries.<br />
<br />
===Install the Open Problem Library ===<br />
The <code>Open Problem Library</code> consists of both WeBWorK problems and methods for searching and selecting problems. Also it contains as sub libraries many of the other standard libraries. We have to load a database for searching it.<br />
<br />
First we put a link to the Open Problem Library in the modelCourse so that when we create courses copying templates from the modelCourse, the OPL will be available.<br />
<br />
$ cd /opt/webwork/courses/modelCourse/templates/<br />
$ ln -s /opt/webwork/libraries/webwork-open-problem-library/OpenProblemLibrary Library<br />
<br />
Note that if the above link is not in the templates directory of a course, it will be automatically created when you open the Library Browser. However, <br />
if e.g. you haven't yet opened the Library Browser and the link is missing and you import problem sets (as we do in section [[#Test that Things are Working Properly|Test that Things are Working Properly]] below), you may see errors <br />
when viewing problems (you definitely will see errors in the Orientation set).<br />
<br />
Next we have to run the <code>OPL-update</code> script which will create the data that the Library Browser uses.<br />
<br />
$ OPL-update<br />
<br />
This has to convert a lot of data for over 37,000 problems so please be patient; it can take a long time.<br />
<br />
If at some time in the future you want to upgrade the Problem Library, the process<br />
is easy, see [[#Updating the OPL|Updating the OPL]]. Note that this is something you should do fairly often so that your library is up to date with<br />
new problems and bug fixes for old ones.<br />
<br />
===Initialize the OPL local statistics database table===<br />
Run the command<br />
$ update-OPL-statistics.pl<br />
to create a table to hold the OPL local statistics. See https://webwork.maa.org/wiki/OPL_Problem_Statistics for information.<br />
<br />
===Set up the access to the Contrib directory ===<br />
<br />
The <code>Contrib</code> directory contains contributions to the OPL that may not have been formally accepted into the main collection of OPL problems. This may be because the contribution is recent and has not yet been reviewed or because the problems are not properly tagged as is the case with the CAPA problem collection. It also contains the original versions of problems that have been accepted into the OPL (the idea being that the original authors maintain control of problems in the <code>Contrib</code> directory but problems in the OPL are controled by the editors). This step creates a button in the Library Browser which gives a direct link to the <code>Contrib</code> directory.<br />
<br />
<br />
Put a link to the Contrib directory in the <code>modelCourse</code> so that when we create courses copying templates from the <code>modelCourse</code>, the Contrib directory will be available. <br />
<br />
$ cd /opt/webwork/courses/modelCourse/templates/<br />
$ ln -s /opt/webwork/libraries/webwork-open-problem-library/Contrib Contrib<br />
<br />
If you just want to do this for individual courses, not all courses then don't put the link in the <code>modelCourse</code> above, and then do the following. Note we don't have any individual courses yet. But for example after creating <code>myTestCourse</code> below, to set up access to the <code>Contrib</code> directory from <code>myTestCourse</code>, do the following<br />
$ cd /opt/webwork/courses/myTestCourse/templates/<br />
$ sudo $ ln -s /opt/webwork/libraries/webwork-open-problem-library/Contrib Contrib<br />
[sudo] password for wwadmin: <wwadmin password><br />
<br />
===Set up the Rochester and Union Libraries ===<br />
<br />
This step is optional. It creates buttons in the Library Browser which give direct links to the Rochester and Union libraries. If you don't do this, you can find these libraries and others under the <code>OPL Directory</code> button.<br />
<br />
First we need to edit <code>localOverrides.conf</code> one last time<br />
<br />
$ cd /opt/webwork/webwork2/conf<br />
$ nano localOverrides.conf<br />
<br />
Search for <code>courseFiles{problibs}</code> and scroll down several lines to the lines<br />
# rochesterLibrary =&gt; "Rochester",<br />
# unionLibrary =&gt; "Union",<br />
Uncomment these lines (i.e. remove the <code>#</code>) so they become <br />
rochesterLibrary =&gt; "Rochester",<br />
unionLibrary =&gt; "Union",<br />
Then save the file and quit.<br />
<br />
We next put links to the Rochester and Union Libraries in the <code>modelCourse</code> so that when we create courses copying templates from the <code>modelCourse</code>, these libraries will be available. Skip this step if you usually only want to use Open Problem Library. Note that the Rochester, Union and other libraries are contained in the OPen Problem Library and are accessible from there under the <code>OPL Directory</code> button in the Library Browser. This step simply creates buttons in the Library Browser so that you can access the Rochester and Union libraries directly.<br />
<br />
$ cd /opt/webwork/courses/modelCourse/templates/<br />
$ ln -s /opt/webwork/libraries/webwork-open-problem-library/OpenProblemLibrary/Union unionLibrary<br />
$ ln -s /opt/webwork/libraries/webwork-open-problem-library/OpenProblemLibrary/Rochester rochesterLibrary<br />
<br />
If you want to put another library into the <code>modelCourse</code>, just do the analogous thing. If you just want the additional library in a particular course, add the link in the <code>templates</code> directory of that course. If you look in the directory <code>/opt/webwork/libraries/webwork-open-problem-library/OpenProblemLibrary/</code> you might find other libraries that are not yet listed in <code>global.conf</code> and these can be added in the same way as the <code>Rochester and </code><code>Union</code> libraries. Finally if you add a library with non standard symbols in the name (e.g. <code>uva-statLibrary</code>) you have to use single quotes when adding it to <code>global.conf</code>, e.g. <br><br />
&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp; <code>'uva-statLibrary' => "UVA-Stat",</code> <br><br />
It's easier to just avoid such names.<br />
<br />
===Install and Set Up the CAPA Library ===<br />
<br />
This step is optional. It installs and sets up [[CAPA Physics Problems|the CAPA Library]], which is a library of physics problems.<br />
<br />
'''Note:''' We are in the process of integrating the CAPA problems into the main distribution so some of the details below may change.<br />
<br />
Move the CAPA graphics files to the required locations and set the group.<br />
<br />
$ cd /opt/webwork/libraries/webwork-open-problem-library/Contrib/CAPA <br />
$ mv CAPA_Graphics /opt/webwork/webwork2/htdocs/<br />
$ sudo chgrp -R wwdata /opt/webwork/webwork2/htdocs/CAPA_Graphics<br />
[sudo] password for wwadmin: <wwadmin password><br />
$ sudo chmod -R g+w /opt/webwork/webwork2/htdocs/CAPA_Graphics <br />
<br />
We need to edit <code>localOverrides.conf</code> again<br />
<br />
$ cd /opt/webwork/webwork2/conf<br />
$ nano localOverrides.conf<br />
<br />
<br />
Now search for the lines<br />
$pg{specialPGEnvironmentVars}{CAPA_Tools} = "$courseDirs{templates}/Contrib/CAPA/macros/CAPA_Tools/",<br />
$pg{specialPGEnvironmentVars}{CAPA_MCTools} = "$courseDirs{templates}/Contrib/CAPA/macros/CAPA_MCTools/",<br />
$pg{specialPGEnvironmentVars}{CAPA_GraphicsDirectory} = "$courseDirs{templates}/Contrib/CAPA/CAPA_Graphics/",<br />
push @{$pg{directories}{macrosPath}},<br />
"$courseDirs{templates}/Contrib/CAPA/macros/CAPA_Tools",<br />
"$courseDirs{templates}/Contrib/CAPA/macros/CAPA_MCTools";<br />
<br />
and replace these six lines by<br />
<br />
################################################################################<br />
#Locations of CAPA resources. (Only necessary if you need to use converted CAPA problems.)<br />
################################################################################<br />
$pg{specialPGEnvironmentVars}{CAPA_Tools} = "$courseDirs{templates}/Contrib/CAPA/macros/CAPA_Tools/",<br />
$pg{specialPGEnvironmentVars}{CAPA_MCTools} = "$courseDirs{templates}/Contrib/CAPA/macros/CAPA_MCTools/",<br />
$pg{specialPGEnvironmentVars}{CAPA_GraphicsDirectory} = "$webworkDirs{htdocs}/CAPA_Graphics/";<br />
$pg{specialPGEnvironmentVars}{CAPA_Graphics_URL} = "$webworkURLs{htdocs}/CAPA_Graphics/";<br />
<br />
<br />
<br />
<br />
Then save the file and Quit.<br />
<br />
There is one final step that is needed. We have to put a link in the templates directory of every course that needs access to the CAPA Library. If you want to have every course you create have access to the CAPA Library (unlikely unless you are in a physics department) put the link in the <code>modelCourse</code>. <br />
$ cd /opt/webwork/courses/modelCourse/templates/<br />
$ ln -s /opt/webwork/libraries/webwork-open-problem-library/Contrib/CAPA/ capaLibrary<br />
<br />
More likely if you just want to do this for individual courses, not all courses then don't put the link in the <code>modelCourse</code> above, and then do the following. We don't have any yet. But for example after creating <code>myTestCourse</code> below, to set up access to the CAPA Library from <code>myTestCourse</code>, do the following<br />
$ cd /opt/webwork/courses/myTestCourse/templates/<br />
$ sudo ln -s /opt/webwork/libraries/webwork-open-problem-library/Contrib/CAPA/ capaLibrary<br />
[sudo] password for wwadmin: <wwadmin password><br />
<br />
<br />
and do the analogous thing for every course that needs access to the CAPA Library.<br />
Then to gain access to the CAPA Library from the course, simply go to the <code>Library Browser</code> and click on the <code>CAPA</code> button.<br />
<br />
<br />
<br />
==Create Your First Actual Course ==<br />
<br />
Since we have edited <code>site.conf</code> and <code>localOverrides.conf</code> and these are critical files, it would be a good idea to run<br />
$ cd /opt/webwork/webwork2/conf<br />
$ diff site.conf site.conf.dist<br />
$ diff localOverrides.conf localOverrides.conf.dist<br />
<br />
and check that you haven't made any mistakes (e.g. by introducing an inadvertent line break, etc.). If there are any mistakes, correct them. Remember that any time you change either of these files you must restart the Apache webserver in order for these changes to take effect. <br />
<br />
Since we have edited <code>global.conf</code> and haven't restarted Apache we do so now.<br />
$ sudo apache2ctl graceful<br />
password:<wwadmin password><br />
<br />
Now log into the <code>admin</code> course ( <code>http://yourserver.yourschool.edu/webwork2/admin</code> or, if you have not hidden the admin course, click on <code>Course Administration</code> on WeBWorK's home page <code>http://yourserver.yourschool.edu/webwork2/</code> ) as yourself or <code>admin</code> and <br />
# click on <code>Add Course</code><br />
# For <code>Course ID</code> enter <code>myTestCourse</code><br />
# For <code>Course Title</code> enter <code>My Test Course</code><br />
# Enter your institution<br />
# Leave <code>Add WeBWorK administrators to new course</code> checked<br />
# Add an additional instructor if you wish<br />
# Copy templates from: <code>modelCourse</code> (the default action)<br />
# Click on <code>Add Course</code><br />
# Click <code>Log into myTestCourse</code><br />
<br />
and log in either as <code>admin</code> or yourself (if you added yourself as an additional instructor above).<br />
<br />
At some point you will probably want to "hide" <code>myTestCourse</code> from general view but you already know how to do that.<br />
<br />
==Test that Things are Working Properly ==<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>.<br />
<br />
Click on <code>Hmwk Sets Editor</code> on the <code>Main Menu</code>. Then select <code>Import</code>, select <code>setDemo.def</code> from the <code>from</code> drop down list and select <code>all current users</code> from the <code>assigning this set to</code> drop down list. Then hit <code>Take Action!</code><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. If not, edit the file <code>Constants.pm</code> in the directory <code>/opt/webwork/webwork2/lib/WeBWorK</code>. Change the line <code>$WeBWorK::PG::ImageGenerator::PreserveTempFiles = 0;</code> to <code>...::PreserveTempFiles = 1;</code>. Then restart Apache and view the first couple problems or some new ones. Then look in the directory <code>/opt/webwork/webwork2/tmp/</code>. <code>cd</code> to one of the <code>ImageGenerator.../tmp/</code> directories and look at the error and log files there. When you fix the problem remember to edit <code>...::PreserveTempFiles = 1;</code> back to 0 and restart Apache or you will be saving a lot of unnecessary files. Another useful trick is to try downloading a hard copy of an assignment and then (assuming there are errors) looking at the various log files that are linked to on the output page.<br />
<br />
Note that since you probably used "admin" to login you have Permission Level "admin" so things look more complicated than if you were just a regular professor with Permission Level "professor". In particular any time you view a problem, you have the option to "Edit tags" which you probably do not want to do. If these bothers you, login as a professor (see below).<br />
<br />
Continue looking at problems to see if everything is working properly.<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 an admin 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>. If you get an error (you shouldn't) just click <code>Download Hardcopy</code> to get what was generated. Also you can see links to various informational files that are available if you run into problems (normally these files are removed if there are no errors). If you want to preserve these tmp files, set <code>$WeBWorK::ContentGenerator::Hardcopy::PreserveTempFiles</code><br />
to 1 in the file <code>Constants.pm</code> in the directory <code>/opt/webwork/webwork2/lib/WeBWorK</code> and then restart Apache. Remember to set this back to 0 after debugging.<br />
<br />
Another thing to do is to use <code>Email</code> on the <code>Main Menu</code>. Again this page is a little complicated because you can do a lot of things with it (including mail merge) but at this point just select yourself in the list to the right and hit <code>Send Email</code> at the bottom. You should receive two emails. One is the message you just sent and the other is an email with subject "WeBWorK email sent" giving information on your mailing. <br />
<br />
As a final test 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. You can also test that you can access any additional Problem Libraries that you installed. Note that if you just happen to view some statistics problems that require the R server, you will get errors (since we have not installed R --- at least not yet).<br />
<br />
'''Note:''' if when using the <code>Library Browser</code> you find that after selecting a <code>Subject</code>, you can not select a <code>Chapter</code> (and usually you will see an error from setmaker.js: /webwork2/instructorXMLHandler: e.g. Timeout or Forbidden),<br />
the most common reason is that $server_root_url has not been set "correctly" in the <code>/opt/webwork/webwork2/conf/site.conf</code> file. A common error is to use forget http:// or to use http:// when you should use https:// or to just have the wrong domain name or ip address. But sometimes "localhost" will work when the correct ip address or url will not, for example in situations when you are using a virtual machine as your host (e.g. on AWS).<br />
<br />
If all the above tests work, you can be pretty confident that WeBWorK is working properly.<br />
<br />
Go back to <code>Hmwk Sets Editor</code> on the <code>Main Menu</code>. Then select <code>Import</code>, select <code>setOrientation.def</code> from the <code>from</code> drop down list and select <code>all current users</code> from the <code>assigning this set to</code> drop down list. Then hit <code>Take Action!</code>. Then go through the Orientation problems. This is a good first set to use for introducing students to WeBWorK. Also you can Import <code>set0.def</code> and <code>setMAAtutorial.def</code> and look through those problems.<br />
<br />
If you are new to WeBWorK or even if you are a pro, you should probably add a regular student to myTestCourse and log in as that student to see what the student interface looks like. It's much simpler than the professor or admin interfaces. Also for the same reason you should probably add professor to myTestCourse and log in as that professor to see what the professor interface looks like.<br />
<br />
Click on <code>Classlist Editor</code> on the <code>Main Menu</code>.<br />
Then select <code>Add</code>, for "Add how many students?" pick 2 and hit <code>Take Action!</code>. Then add two students, say <br />
<br />
* <code>Last Name</code> "Smith", <code>First Name</code> "Jane" , <code>Student ID</code> "jsmith" and <code>Login Name</code> "jsmith"<br />
<br />
* <code>Last Name</code> "A", <code>First Name</code> "Prof" , <code>Student ID</code> "profa" and <code>Login Name</code> "profa"<br />
and make sure to select all sets to assign them to both of them. Then hit <code>Add Students</code>.<br />
<br />
Now we make "profa" a professor. Again click on <code>Classlist Editor</code> on the <code>Main Menu</code>. The fast way is to click on the "pencil" by "profa", set the "Permission Level" to "professor" and hit <code>Take Action!</code>.<br />
<br />
Jane Smith's initial password will be her <code>Student ID</code> <code>jsmith</code>. Now login as Jane Smith and play around a little. <br />
<br />
Prof A's initial password will be her <code>Student ID</code> <code>profa</code>. You should also login as Prof A and play around a little. <br />
<br />
You can also add "practice users" and login as one of those to see how you can grant partial access to your course for practice or other reasons (e.g. auditors who don't want to be graded). To do this Click on <code>Classlist Editor</code>, select <code>Import</code>, select the "demoCourse.lst" (the only classlist available at this point) and hit <code>Take Action!</code>.<br />
<br />
==Optional Configurations==<br />
*'''Optional A''' stores WeBWorK's "temporary" files in a separate partition (or directory). <br />
*'''Optional B''' installs and configures a lightweight webserver to serve static files.<br />
*'''Optional C''' configures Apache so that access to WeBWorK will be through SSL.<br />
*'''Optional D''' installs and configures the R server for statistical computing.<br />
*'''Optional E''' sets up log rotation for WeBWorK's timing log.<br />
<br />
===Implement Optional A (wwtmp)===<br />
<br />
Now is the time to implement '''Optional A''' if you choose to do so. Actually you can do this at any time and your active courses will continue to function seemingly without change. The only change behind the scenes will be that temporary files will be stored in a different location. Note that if you want to use this option but did not create <code>wwtmp</code> as a separate partition, you first have to create the directory <code>/var/www/html/wwtmp</code> with the command<br />
sudo mkdir /var/www/html/wwtmp <br />
[sudo] password for wwadmin: <wwadmin password><br />
All of WeBWorK's "temporary" files will be stored under <code>/var/www/html/wwtmp</code>. These are mostly small files such as png images of equations, pdf files, etc. that may be reused but if they are not present (e.g. if they get deleted) they will be seamlessly regenerated on the fly. There is no reason to back up such files and having them in a separate partition or directory means that it is easier and faster to back up other partitions and skip backing up unnecessary files. Even if you do not want to set up a separate partition for this, it is very convenient to at least set up a separate directory for these temporary files and we recommend that yo do so.<br />
<br />
First we set the group and permissions for the <code>wwtmp</code> directory<br />
$ sudo -s<br />
[sudo] password for wwadmin: <wwadmin password><br />
# cd /var/www/html<br />
# chown wwadmin wwtmp<br />
# chgrp wwdata wwtmp<br />
# chmod ug+w wwtmp<br />
# chmod g+s wwtmp<br />
# exit<br />
$<br />
Next we have to edit <code>localOverrides.conf</code> so that WeBWorK uses the new <code>wwtmp</code> directory. Since we have a working WeBWorK system, first we make a backup copy of <code>localOverrides.conf</code>.<br />
$ cd /opt/webwork/webwork2/conf<br />
$ cp localOverrides.conf localOverrides.conf.bak1<br />
$ nano localOverrides.conf<br />
Now edit <code>localOverrides.conf</code>. Search for the line<br />
# Directory for temporary files<br />
and under that find the line<br />
# To implement, uncomment the following 6 lines:<br />
Then uncomment (i.e. remove the # symbol) from the 6 lines<br />
#$webworkDirs{htdocs_temp} = '/var/www/html/wwtmp';<br />
#$webworkURLs{htdocs_temp} = '/wwtmp';<br />
#$webworkDirs{equationCache} = "$webworkDirs{htdocs_temp}/equations";<br />
#$webworkURLs{equationCache} = "$webworkURLs{htdocs_temp}/equations";<br />
#$courseDirs{html_temp} = "/var/www/html/wwtmp/$courseName";<br />
#$courseURLs{html_temp} = "/wwtmp/$courseName";<br />
<br />
'''IMPORTANT NOTE'''. Apache 2.4 has changed the default location of the document root from <code>/var/www</code> to <br />
<code>/var/www/html</code> and we are in the process of updating the file <code>localOverrides.conf.dist</code> to reflect this.<br />
If your copy of this file does not have <code>/html</code> in the two lines above, then in addition to uncommenting the 6 lines you also have to add <code>/html</code> in two places.<br />
<br />
Then save the file and quit. If you look at the <code>wwtmp</code> directory you will find it empty but after you restart apache and then access some WeBWorK problems, you will find temporary directories and files in <code>wwtmp</code>. Remember your have to restart apache for these changes to take effect.<br />
<br />
====Using Cron Jobs to remove temporary files====<br />
<br />
It is a good idea to clean out temporary files on a regular automatic schedule. Also pdf copies of downloaded problem sets are saved in a temporary directory (<code>wwtmp/.../hardcopy</code>) so that they can be downloaded from the web. But after the download, the pdf file remains and is visible from the web if one knows the URL. For this reason we recommend deleting all such files that are over one hour old. Similarly we recommend deleting all png, gif, and html links under <code>wwtmp</code> that are over 30 days old. And finally every week we recommend deleting all equation images that are over 14 days old. The following cron jobs will accomplish this. The first is run every 30 minutes, the next three twice a month and the last one weekly on Sunday morning. These cron jobs should be run as root. We use <code>crontab</code> to edit the <code>crontab</code> file:<br />
$ sudo -s<br />
[sudo] password for wwadmin: <wwadmin password><br />
# crontab -e<br />
<br />
Now add the following lines at the end of the file<br />
<br />
WEBWORK_ROOT=/opt/webwork/webwork2<br />
*/30 * * * * find /var/www/html/wwtmp/*/hardcopy/* -mmin +60 -name "*" -delete<br />
5 5 1,15 * * find /var/www/html/wwtmp/*/gif/ -mtime +30 -name "*" -delete<br />
5 5 2,16 * * find /var/www/html/wwtmp/*/png/ -mtime +30 -name "*" -delete<br />
5 5 3,17 * * find /var/www/html/wwtmp/*/html/ -mtime +30 -name "*" -delete<br />
4 5 * * 0 /opt/webwork/webwork2/bin/remove_stale_images --delete --days 14<br />
<br />
and save the file and quit<br />
# exit<br />
$<br />
<br />
===Implement Optional B (lighttpd)===<br />
<br />
As is the case for '''Optional A''' you can implement '''Optional B''' at any time and your active courses will continue to function seemingly without change. The only change behind the scenes will be that static images, pages and MathJax (if you installed it locally) will be served by a light weight web server.<br />
====Install and Configure lighttpd====<br />
First we install the light weight webserver <code>lighttpd</code><br />
<br />
Run the command <br />
$ sudo apt install lighttpd<br />
[sudo] password for wwadmin: <wwadmin password><br />
<br />
Now we configure <code>lighttpd</code>. First let's make a backup of the configuration file.<br />
<br />
<br />
$ cd /etc/lighttpd<br />
$ sudo cp lighttpd.conf lighttpd.conf.bak1<br />
[sudo] password for wwadmin: <wwadmin password><br />
<br />
Now edit <code>lighttpd.conf</code>. <br />
<br />
$ sudo nano lighttpd.conf<br />
<br />
<br />
Apache2 is listening on port 80 so we need an alternate port for lighttp to listen to. Standard alternate ports for this are usually 81, 8000, or 8080. 8080 is the only port that is listed as an official alternate at http://en.wikipedia.org/wiki/List_of_TCP_and_UDP_port_numbers . Note that in rare cases an institution may block httpd requests to port 8080. If any of your students report that they can not see graphics, they will have to request that access to requests to port 8080 be allowed.<br />
<br />
Find the line<br />
server.port = 80<br />
and replace it by<br />
server.port = 8080<br />
<br />
Now we make a few more changed that allow MathJax to run under lighttpd. You can skip these if you are running MathJax remotely. At the top of the file in the section <code> server.modules = </code>, under the line<br />
"mod_redirect",<br />
add the line<br />
"mod_setenv",<br />
Then below the closing parentheses and above the line <br />
server.document-root = "/var/www/html"<br />
add the lines<br />
setenv.add-response-header = ( "Access-Control-Allow-Origin" => "*" )<br />
alias.url = ( "/webwork2_files" => "/opt/webwork/webwork2/htdocs/" )<br />
<br />
Then save the file and quit.<br />
<br />
Now restart lighttp<br />
$ sudo systemctl restart lighttpd<br />
<br />
====Test lighttpd====<br />
First run the command<br />
$ sudo lsof -i -P -n | grep LISTEN<br />
and check that lighttpd is listening on port 8080<br />
<br />
Now test your server by connecting to your<br />
server from a browser on a remote machine ("http://yourserver.yourschool.edu:8080/"). You should see the '''Apache2 Ubuntu Default Page''' but without a graphic for the Ubuntu Logo indicating that lighttp is running . Test the <code>/webwork2_files</code> location by visiting "http://yourserver.yourschool.edu:8080/webwork2_files</code>. You should see the "WeBWorK Placeholder Page".<br />
<br />
====Configure WeBWorK to Take Advantage of Lighttp====<br />
<br />
First let's make a backup copy of <code>localOverrides.conf </code> so that we can easily back out of these changes if necessary.<br />
<br />
$ cd /opt/webwork/webwork2/conf<br />
$ cp localOverrides.conf localOverrides.conf.bak2<br />
<br />
<br />
Now edit <code>localOverrides.conf</code>. Note that while '''Optional B''' is independent of '''Optional A''', we assume most people implementing '''Optional B''' will have already implemented '''Optional A'''. Therefore we give instructions for editing <br />
localOverrides.conf assuming that '''Optional A''' has been implemented. If this is not the case, modify the instructions below accordingly. Also replace <code>yourserver.yourschool.edu</code> with the correct address.<br />
<br />
$ nano localOverrides.conf<br />
<br />
Find the line<br />
$webworkURLs{htdocs_temp} = '/wwtmp'<br />
and replace it by<br />
#$webworkURLs{htdocs_temp} = '/wwtmp';<br />
$webworkURLs{htdocs_temp} = 'http://yourserver.yourschool.edu:8080/wwtmp';<br />
<br />
<br />
Find the line<br />
$courseURLs{html_temp} = "/wwtmp/$courseName";<br />
and replace it by<br />
#$courseURLs{html_temp} = "/wwtmp/$courseName";<br />
$courseURLs{html_temp} = "http://yourserver.yourschool.edu:8080/wwtmp/$courseName";<br />
<br />
If you installed MathJax locally under the above line add the lines<br />
# Location of MathJax script, used for the MathJax display mode.<br />
$webworkURLs{MathJax} = 'http://yourserver.yourschool.edu:8080/webwork2_files/mathjax/MathJax.js?config=TeX-MML-AM_HTMLorMML-full';<br />
If you are running MathJax remotely, '''don't add the above lines'''.<br />
<br />
Then save the file and quit.<br />
<br />
Now restart apache and lighttp.<br />
<br />
$ sudo apache2ctl graceful<br />
password:<wwadmin password><br />
$ sudo systemctl restart lighttpd<br />
<br />
====Test that Everything is Working Properly====<br />
<br />
To test things go to your test course <code>http://yourserver.yourschool.edu/webwork2/myTestCourse/</code>. Log into your course and view a problem with a graphic image (e.g. Problem 2 of the Demo set. Since you have Admin or Prof privileges, you can view sets which are not yet open). Right click on the image and click on Properties (or whatever is appropriate on your browser, e.g. copy image location) and check that the image is being served from port 8080 (something like <code>http://yourserver.yourschool.edu:8080/wwtmp/myTestCourse//gif/...</code>). <br />
<br />
If MathJax is installed locally, to test that MathJax is using lighttpd, view a problem with some typeset equations. Right click on the equation and you should see the MathJax menu which confirms MathJax is being used. Next look at the source code for the page (e.g. right click on most browsers and select "View page source") and in the source, search for mathjax.js. You should see that this is being loaded from port 8080. Obviously, if you are running MathJax remotely, you will see it is being loaded from the CDN.<br />
<br />
====Disabling Optional B (lighttpd) for a single course====<br />
<br />
If your server is hosting courses from different institutions, you may find that you need to disable using lighttpd for a single course, e.g. because the institution blocks access to port 8080. Actually since port 8080 is an "official" alternate httpd port, you should first try to get the network administrators at the institution to grant access to port 8080. Failing this, you can disable using lighttpd and instead use apache for a single course by adding the following lines to the end of the course's <code>course.conf</code> file which is located in the top level directory for the course (usually <code>/opt/webwork/courses/course_name</code>). Note that using apache instead of lighttpd will put a slightly larger load on the server. Also note that you need "admin" level privileges to edit the <code>course.conf</code> file. Instructors with only "professor" level privileges can not do this from within WeBWorK.<br />
If you are running MathJax remotely, don't add the last line.<br />
# Do not use lightppd (port 8080) for this course<br />
$webworkURLs{htdocs_temp} = '/wwtmp';<br />
$courseURLs{html_temp} = "/wwtmp/$courseName";<br />
$webworkURLs{equationCache} = "$webworkURLs{htdocs_temp}/equations";<br />
$webworkURLs{MathJax} = "$webworkURLs{htdocs}/mathjax/MathJax.js?config=TeX-MML-AM_HTMLorMML-full";<br />
'''I repeat if you are running MathJax remotely, don't add the last line above.'''<br />
<br />
===Implement Optional C (SSL)===<br />
'''Optional C''' configures apache so that access to WeBWorK will be through an encrypted connection (SSL) with an https: URL. 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. If you have implemented '''Optional B''', the non encrypted lighttpd server will be used for images, MathJax, etc. so we might have to set up the lighttpd server to run under SSL (see below).<br />
<br />
First we have to obtain an official SSL certificate or generate a self-signed one which can be used for testing purposes. If students will be using your server, it is better to obtain an official SSL certificate since using a self-signed certificate with cause warning messages to be displayed when students connect to the server.<br />
<br />
====Obtain an Official SSL Certificate====<br />
Talk to the networking group on your campus about obtaining an official certificate. You can find information on the net about certificate providers, e.g. http://www.sslshopper.com/certificate-authority-reviews.html .<br />
<br />
The certificate goes in <code>/etc/ssl/certs/</code> and the key file goes in <code>/etc/ssl/private/</code>.<br />
<br />
====Use a self-signed Certificate====<br />
<br />
When we installed the package openssh-server a self-signed certificate was automatically created. The certificate is stored at<br />
/etc/ssl/certs/ssl-cert-snakeoil.pem<br />
and the private key at<br />
/etc/ssl/private/ssl-cert-snakeoil.key<br />
<br />
This certificate and key may be regenerated manually with the following command (needs root privileges ie sudo):<br />
<br />
$ sudo make-ssl-cert generate-default-snakeoil --force-overwrite<br />
[sudo] password for wwadmin: <wwadmin password><br />
<br />
which you might want to do since I believe the original certificate is only valid for 365 days.<br />
<br />
In the instructions below we will use the provided self-signed certificate (ssl-cert-snakeoil.pem and ssl-cert-snakeoil.key) but you can also generate your own using openssh following instructions on the web. As we said above, for a production server, you should really use an official certificate.<br />
<br />
====Set up Apache to use SSL====<br />
<br />
First we enable the <code>mod_ssl</code> module<br />
$ sudo a2enmod ssl<br />
[sudo] password for wwadmin: <wwadmin password><br />
<br />
Now we have to configure Apache to use SSL.<br />
$ cd /etc/apache2/sites-available/<br />
$ sudo cp default-ssl.conf default-ssl.conf.bak1<br />
[sudo] password for wwadmin: <wwadmin password><br />
$ sudo nano default-ssl.conf<br />
<br />
Our self-signed certificate and key files are named <br />
<code>ssl-cert-snakeoil.pem</code> and <code>ssl-cert-snakeoil.key</code>. If you<br />
are using official files, put their names in the lines below. You will also have to edit the Certificate Chain, Certificate Authority and possibly other items. Instructions for doing so are beyond the scope of this document. You might look at https://www.digitalocean.com/community/tutorials/how-to-secure-apache-with-let-s-encrypt-on-ubuntu-18-04<br />
<br />
Search for the lines<br />
SSLCertificateFile /etc/ssl/certs/ssl-cert-snakeoil.pem<br />
SSLCertificateKeyFile /etc/ssl/private/ssl-cert-snakeoil.key<br />
and replace <code>ssl-cert-snakeoil.pem</code> and <code>ssl-cert-snakeoil.key</code> by the names of your certificate. Since in these instructions we are using <br />
<code>ssl-cert-snakeoil.pem</code> and <code>ssl-cert-snakeoil.key</code>, we can just leave the lines as is.<br />
<br />
Then save the file and quit. And enable <code>default-ssl.conf</code> <br />
$ sudo a2ensite default-ssl.conf<br />
[sudo] password for wwadmin: <wwadmin password><br />
Finally we restart Apache<br />
$ sudo systemctl restart apache2<br />
and test things. Connect to https://yourserver.yourschool.edu/webwork2/myTestCourse<br />
You will be asked to accept the certificate. After you do so things should work just as before except that the connection will be via https except for images, MathJax, etc. if you using lighttp. In that case, viewing math expressions in image mode should work fine but it is possible using MathJax mode will fail. We will talk about this below.<br />
<br />
====Redirect http requests to https====<br />
Assuming that everything is working, the last thing we do is set things up so that requests to http://yourserver.yourschool.edu/webwork2/ are automatically redirected to https://yourserver.yourschool.edu/webwork2/.<br />
<br />
$ cd /etc/apache2/sites-available<br />
$ sudo cp 000-default.conf 000-default.conf.bak1<br />
[sudo] password for wwadmin: <wwadmin password><br />
$ sudo nano 000-default.conf<br />
<br />
In the <br />
<VirtualHost *:80><br />
section just under the line<br />
DocumentRoot /var/www/html<br />
add the line<br />
Redirect permanent /webwork2 https://yourserver.yourschool.edu/webwork2<br />
where of course you should edit <code>yourserver.yourschool.edu</code> appropriately.<br />
Then save the file and quit.<br />
Restart Apache<br />
$ sudo service apache2 restart<br />
and try connecting to http://yourserver.yourschool.edu/webwork2/. The real connection should be through https://yourserver.yourschool.edu/webwork2/.<br />
<br />
====Check site.conf====<br />
This is important. We have to check the value of $server_root_url in webwork2/conf/site.conf to make <br />
sure it uses https (so it should read e.g. https://yourserver.yourschool.edu). If<br />
you don't do this, your may run into strange problems in the Library Browser.<br />
To check, open the Library Browser, select a subject and then click on the chapter area. If you see a drop down list of chapters, things are working properly. <br />
<br />
Now we check and edit if necessary site.conf<br />
cd /opt/webwork/webwork2/conf<br />
nano site.conf<br />
<br />
In the line<br />
$server_root_url = ...<br />
replace http by https if necessary. Then save the file, quit and restart apache<br />
sudo service apache2 restart <br />
[sudo] password for wwadmin: <wwadmin password><br />
<br />
===Configure lighttpd to use SSL===<br />
<br />
We are using lighttpd for images, pdf's and MathJax (if MathJax is installed locally) MathJax may fail (so mathematical expressions will not be displayed) if it runs under lighttpd and you do not configure lighttpd to use SSL. So let's configure lighttpd to use SSL.<br />
<br />
For lighttpd you need to concatenate the key file and the certificate file into a single pem file by running the following command.<br />
Obviously you should use the real name of your certificate and key files, not "apache.key" and "apache.crt".<br />
<br />
$ sudo -s<br />
[sudo] password for wwadmin: <wwadmin password><br />
# cd /etc/ssl/private<br />
# cat apache.key ../certs/apache.crt > apache.pem<br />
# chmod 640 apache.pem<br />
# exit<br />
$<br />
<br />
If you are using official certificates,<br />
you will also have to edit the Certificate Chain, Certificate Authority and possibly other items. Instructions for doing so are beyond the scope of this document. See e.g.<br />
http://redmine.lighttpd.net/projects/lighttpd/wiki/Docs_SSL and/ or https://www.vultr.com/docs/setup-let-s-encrypt-with-lighttpd-on-ubuntu-16-04 <br />
<br />
<br />
Since we already are using the files <code>ssl-cert-snakeoil.pem</code> and <code>ssl-cert-snakeoil.key</code> for apache, we will also use them for lighttpd<br />
<br />
$ sudo cat /etc/ssl/private/ssl-cert-snakeoil.key /etc/ssl/certs/ssl-cert-snakeoil.pem >/etc/lighttpd/lighttpd.pem<br />
[sudo] password for wwadmin: <wwadmin password><br />
<br />
Now edit <code>lighttpd.conf</code>. <br />
$ cd /etc/lighttpd<br />
$ sudo cp lighttpd.conf lighttpd.conf.bak2<br />
[sudo] password for wwadmin: <wwadmin password><br />
$ sudo nano lighttpd.conf<br />
<br />
First in the list of <code>server.modules</code> at the top of the file, under the last module <code>"mod_setenv",</code>, add the module<br />
"mod_openssl",<br />
<br />
Next under the line<br />
server.port = 8080<br />
add the following<br />
$SERVER["socket"] == ":8443" {<br />
ssl.engine = "enable"<br />
ssl.pemfile = "/etc/lighttpd/lighttpd.pem"<br />
}<br />
<br />
Then save the file and quit.<br />
<br />
And restart lighttpd and check it's status<br />
<br />
$ sudo systemctl restart lighttpd<br />
[sudo] password for wwadmin: <wwadmin password><br />
$ sudo systemctl status lighttpd<br />
<br />
Sometimes when Lighttpd would not restart (or start) I just rebooted the server and everything worked. If you have difficulty you can run the command<br />
$ sudo lsof -i -P -n | grep LISTEN<br />
which will list all the ports your server is listening to. In the list you should see something similar to<br />
lighttpd 519 www-data 5u IPv4 18610 0t0 TCP *:8443 (LISTEN)<br />
<br />
<br />
====Edit localOverrides.conf</code>====<br />
$ cd /opt/webwork/webwork2/conf<br />
$ cp localOverrides.conf localOverrides.conf.bak4<br />
$ nano localOverrides.conf<br />
and replace all occurrences of 8080 by 8443 (one occurrence in three different lines). Then in these same three lines replace <code>http</code> by <code>https</code> . Obviously, you have to edit the three active lines and can ignore the commented out lines.<br />
<br />
Then save the file and quit. And restart apache<br />
$ sudo service apache2 restart<br />
[sudo] password for wwadmin: <wwadmin password><br />
<br />
and test that all is well by viewing a page with math expressions using MathJax mode.<br />
<br />
===Implement Optional D (Rserve)===<br />
<br />
Here we will install and configure the R server for statistical computing. Many statistics and probability problems (mostly contributed by faculty at the University of British Columbia) require this.<br />
<br />
See the documentation (from which we have borrowed heavily) [[R_in_WeBWorK]] for more detailed information.<br />
<br />
====Install the R server====<br />
$ sudo apt install r-cran-rserve<br />
[sudo] password for wwadmin: <wwadmin password><br />
<br />
and check that R is running<br />
$ R<br />
<br />
You should see something very similar to <br />
<br />
R version 3.6.3 (2020-02-29) -- "Holding the Windsock"<br />
Copyright (C) 2020 The R Foundation for Statistical Computing<br />
...<br />
Type 'q()' to quit R.<br />
<br />
><br />
and then quit<br />
> q()<br />
Save workspace image? [y/n/c]: n<br />
<br />
====Configure Webwork with the location of the R server====<br />
Edit the localOverrides.conf file<br />
<br />
$ cd /opt/webwork/webwork2/conf<br />
$ nano localOverrides.conf<br />
<br />
Search for the line<br />
$pg{specialPGEnvironmentVars}{DragMath}<br />
and under that line add the following<br />
<br />
################################################################################<br />
#location of the R server<br />
################################################################################<br />
$pg{specialPGEnvironmentVars}{Rserve} = {host => 'localhost'};<br />
<br />
Then save the file and Quit.<br />
<br />
====Set up Rserve to run as a daemon at system boot====<br />
<br />
This is somewhat complicated. I'm basically following instructions from https://github.com/geordielad/rserve-systemd-unit<br />
<br />
First we create a user with limited privileges to run rserve.<br />
<br />
$ sudo adduser rserveuser --system --shell=/bin/false --no-create-home --disabled-password --disabled-login<br />
<br />
<br />
Next we create a file to automatically start Rserve<br />
<br />
$ cd<br />
$ nano rserve.service<br />
Now copy and paste the following code into nano<br />
<br />
[Unit]<br />
Description=Rserve<br />
<br />
[Service]<br />
Type=forking<br />
PIDFile=/var/run/rserve/rserve.pid<br />
<br />
# Define runtime directory<br />
RuntimeDirectory=rserve<br />
RuntimeDirectoryMode=750<br />
<br />
User=rserveuser<br />
Group=nogroup<br />
<br />
ExecStart=/usr/bin/R CMD Rserve --quiet --vanilla --RS-pidfile /var/run/rserve/rserve.pid<br />
<br />
[Install]<br />
WantedBy=multi-user.target<br />
<br />
and then save the file and quit.<br />
Change the owner to root, move the file to the proper location and register it.<br />
<br />
$ sudo chown root:root rserve.service<br />
[sudo] password for wwadmin: <wwadmin password><br />
$ sudo mv rserve.service /etc/systemd/system<br />
$ sudo systemctl daemon-reload<br />
<br />
Finally we enable the service to start when the system starts<br />
<br />
$ sudo systemctl enable rserve.service<br />
<br />
====Test that things are working properly====<br />
<br />
First start Rserve manually<br />
$ sudo systemctl start rserve<br />
[sudo] password for wwadmin: <wwadmin password><br />
and run <br />
$ sudo lsof -i -P -n | grep LISTEN<br />
and you should see that Rserve is listening on port 6311<br />
<br />
Next test that WeBWorK problems using R run properly. In WeBWorK, click on <code>Library Browser</code> on the <code>Main Menu</code>. Then click <code>Open Problem Library </code> (actually it should already be selected so it will be greyed out). <br />
Now 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 />
<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 />
Finally reboot your server (to test that the Rserve starts automatically on boot up) and run <br />
$ sudo systemctl status rserve.service<br />
[sudo] password for wwadmin: <wwadmin password><br />
to check that all is well and just to be redundant <br />
$ sudo lsof -i -P -n | grep LISTEN<br />
again. Now we are sure that Rserve automatically starts when the system is booted.<br />
<br />
====Loading additional modules====<br />
This step should not be necessary unless you are writing or using WeBWorK problems that need additional resources beyond what is loaded by default. An example is using R to compute complex eigenvalues which requires the <code>Math::Complex</code> module (see https://webwork.maa.org/moodle/mod/forum/discuss.php?d=5577). The error message in such a case would be similar to <br />
Can't locate object method "make" via package "Math::Complex" (perhaps you forgot to load "Math::Complex"?) at /usr/share/perl/5.30/Math/Complex.pm line 329<br />
Died within Math::Complex::cplx called at line 351 of /usr/local/share/perl/5.30.0/Statistics/R/IO/QapEncoding.pm<br />
from within Statistics::R::IO::QapEncoding::decode called at line 236 of /usr/local/share/perl/5.30.0/Statistics/R/IO/Rserve.pm<br />
from within Statistics::R::IO::Rserve::eval called at line 26 of [PG]/lib/Rserve.pm<br />
from within Rserve::try_eval called at line 146 of [PG]/macros/RserveClient.pl<br />
from within main::rserve_eval called at line 40 of (eval 4456)<br />
<br />
First note that the required module must be installed on your server (see [[#Installing Perl Modules|Installing Perl Modules]] above). The <code>Math::Complex</code> module already is.<br />
<br />
We need to load <code>Math::Complex</code> into WeBWorK's safe compartment. For this we have to edit the localOverrides.conf file.<br />
<br />
$ cd /opt/webwork/webwork2/conf<br />
$ nano localOverrides.conf<br />
Now search for the line<br />
# Additional PG modules<br />
and under the line<br />
#push (@{${pg}{modules}}, [qw(TikZ_Image2)]);<br />
add the lines<br />
push @{$pg{modules}},<br />
[qw( Math::Complex )],<br />
; <br />
You can add as many modules as you need this way.<br />
<br />
Then save the file and Quit.<br />
<br />
===Implement Optional E (Logrotate)===<br />
Here we will set up log rotation for WeBWorK's timing log which can grow huge especially if you have a large number of users. The <code>timing.log</code> gives timing information on every action in WeBWorK (see [[WeBWorK_performance]]) and can be used to assess the performance of your server.<br />
<br />
====Create a WeBWorK configuration file for Logrotate====<br />
Logrotate’s configuration files are located in <code>/etc/logrotate.d</code>. Now we create one for WeBWorK.<br />
<br />
$ sudo nano /etc/logrotate.d/webwork<br />
<br />
Now copy and paste the following code into nano<br />
/opt/webwork/webwork2/logs/timing.log {<br />
su www-data wwdata<br />
weekly<br />
missingok<br />
rotate 15<br />
compress<br />
delaycompress<br />
notifempty<br />
}<br />
and then save the file and quit. The backup will be done weekly and we are keeping 15 weeks (approximately one semester) worth of logs. <br />
The most recent backup will not be compressed but all older ones will be. We are not explicitly creating a new <code>timing.log</code> file <br />
because WeBWorK will automatically create one if it's missing. If you want to check that it works you can run <code>logrotate</code><br />
with the configuration file (make sure you have done something with WeBWorK so that the <code>timing.log</code> is not empty):<br />
<br />
sudo logrotate -f /etc/logrotate.d/webwork<br />
[sudo] password for wwadmin: <wwadmin password><br />
<br />
Then if you look in <code>/opt/webwork/webwork2/logs</code>, you should see<br />
<br />
timing.log.1<br />
<br />
You will not see a <code>timing.log</code> file unless someone has been doing something with WeBWorK. If there is no <code>timing.log</code> file<br />
do something yourself (e.g. login to a course) and then you should see <br />
<br />
timing.log<br />
timing.log.1<br />
<br />
Now run <code>logrotate</code> again <br />
sudo logrotate -f /etc/logrotate.d/webwork<br />
[sudo] password for wwadmin: <wwadmin password><br />
and do something in WeBWorK and you should see<br />
<br />
timing.log<br />
timing.log.1<br />
timing.log.2.gz<br />
<br />
Here is what is going on. <code>timing.log.1</code> was renamed to <code>timing.log.2</code> and compressed giving <code>timing.log.2.gz</code>. <code>timing.log</code> was renamed to <code>timing.log.1</code>. <br />
And the something you (or someone else) did in WeBWorK created a new <code>timing.log</code> file. A similar procedure will happen weekly until there are a total of <br />
15 backups after which the oldest one will be deleted.<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. <br />
<br />
To fix this 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", "HTML_tth", ],<br />
<br />
Then save the file and Quit.<br />
<br />
This may or may not be addressed in a WeBWorK 15 hotfix (see [[#Checking for and Installing Hotfixes|Checking for and Installing Hotfixes]]).<br />
<br />
===UTF-8 support===<br />
WW 2.15 has some "known issues" with the UTF-8 support that arise in some WeBWorK problems. These issues are discussed in a forum discussion at: <br />
https://webwork.maa.org/moodle/mod/forum/discuss.php?d=4795. The discussion there lists pull requests by <br />
Nathan Wallach and Davide Cervone that address these issues. If you write or use WeBWorK problems that have issues with UTF-8 characters,<br />
look at that discussion. Again these issues may or may not be addressed in a WeBWorK 15 hotfix (see [[#Checking for and Installing Hotfixes|Checking for and Installing Hotfixes]]).<br />
<br />
Systems using UTF-8 problems probably need to patch /usr/share/perl5/XMLRPC/Lite.pm as explained at https://github.com/openwebwork/webwork2/issues/967#issuecomment-523941959 and may want to consider the fixes accepted in the develop branch via https://github.com/openwebwork/webwork2/pull/1089 and https://github.com/openwebwork/pg/pull/466 .<br />
<br />
==Where to go From Here ==<br />
<br />
You should play around with <code>myTestCourse</code> e.g. click on <code>Library Browser</code> and browse the <code>Problem Library</code>.<br />
<br />
Look at [[A day in the life of a WeBWorK instructor]].<br />
<br />
Read [[Course Administration]] for more information about creating courses.<br />
<br />
Under Categories below click on Administrators to see a listing of other WeBWorK documentation for system administrators.<br />
<br />
-- Main.ArnoldPizer update by Peter Staab - 19 May 2021 <br /><br />
<br />
[[Category:Administrators]]<br />
[[Category:Installation Manuals]]</div>141.154.51.251https://webwork.maa.org/mediawiki_new/index.php?title=Installation_Manual_for_2.16_on_Ubuntu&diff=20909Installation Manual for 2.16 on Ubuntu2021-05-19T20:45:49Z<p>141.154.51.251: /* Securing the DataBase */</p>
<hr />
<div><br />
{{UnderConstruction}}<br />
<br />
'''These instructions are a work in progress. '''<br />
<br />
<br />
These instructions cover the installation of WeBWorK 2.16 for Ubuntu Server 20.04 LTS, XXX and XXX. Specific OS instruction are embedded within this document<br />
<br />
If you are just upgrading WeBWorK, especially if you already have existing WeBWorK courses, see [[Upgrading_WeBWorK_with_Github]].<br />
<br />
Also, it is assumed that you have an operating system installed. You can visit [[Category:Installation_Manuals]] for instructions on installing the operating system or google how to install your favorite linux flavor. Also make sure the OS is upgraded to all patches within the version you are running. <br />
<br />
== Notation ==<br />
<br />
First some short comments on notation we will be using. We will use <code>&lt;key&gt;</code> to indicate that you should press a specific key (e.g. <code>&lt;Enter&gt;</code>, <code>&lt;Tab&gt;</code>, <code>&lt;F12&gt;</code>, etc.). Sometimes we will also use e.g. <code>&lt;wwadmin password&gt;</code> to indicate you have to enter the wwadmin password.<br />
<br />
<code>^</code> will indicate the <code>&lt;Ctrl&gt;</code> key so e.g. <code>^X</code> is really shorthand for <code>&lt;Ctrl&gt; &lt;X&gt;</code>, i.e. press the Ctrl key and hit the X key.<br />
<br />
==Install Software Packages==<br />
<br />
=== Ubuntu Software Packages ===<br />
<br />
On Ubuntu and other Debian linuxes, the following instructions will get needed software packages installed. <br />
<br />
Here is the list of Ubuntu packages that need to be installed. <br />
<br />
# <code>apache2</code><br />
# <code>cpanminus</code><br />
# <code>curl</code><br />
# <code>dvipng</code><br />
# <code>gcc</code><br />
# <code>git</code><br />
# <code>imagemagick</code><br />
# <code>libapache2-request-perl</code><br />
# <code>libarchive-zip-perl</code><br />
# <code>libarray-utils-perl</code><br />
# <code>libcrypt-ssleay-perl</code><br />
# <code>libdatetime-perl</code><br />
# <code>libdata-dump-perl</code><br />
# <code>libemail-address-xs-perl</code><br />
# <code>libemail-sender-perl</code><br />
# <code>libexception-class-perl</code><br />
# <code>libextutils-xsbuilder-perl</code><br />
# <code>libfile-find-rule-perl-perl</code><br />
# <code>libgd-perl</code><br />
# <code>libhtml-scrubber-perl</code><br />
# <code>libhttp-async-perl</code><br />
# <code>libiterator-perl</code><br />
# <code>libiterator-util-perl</code><br />
# <code>libjson-perl</code><br />
# <code>liblocale-maketext-lexicon-perl</code><br />
# <code>libmime-tools-perl</code><br />
# <code>libmoox-options-perl</code><br />
# <code>libnet-ip-perl</code><br />
# <code>libnet-ldap-perl</code><br />
# <code>libnet-oauth-perl</code><br />
# <code>libossp-uuid-perl</code><br />
# <code>libpadwalker-perl</code><br />
# <code>libpath-class-perl</code><br />
# <code>libphp-serialization-perl</code><br />
# <code>libpod-wsdl-perl</code><br />
# <code>libsoap-lite-perl</code><br />
# <code>libsql-abstract-perl</code><br />
# <code>libstring-shellquote-perl</code><br />
# <code>libtemplate-perl</code><br />
# <code>libtext-csv-perl</code><br />
# <code>libtimedate-perl</code><br />
# <code>libuuid-tiny-perl</code><br />
# <code>libxml-parser-easytree-perl</code><br />
# <code>libxml-parser-perl</code><br />
# <code>libxml-writer-perl</code><br />
# <code>make</code><br />
# <code>netpbm</code><br />
# <code>npm</code><br />
# <code>pdf2svg</code><br />
# <code>preview-latex-style</code><br />
# <code>texlive</code><br />
# <code>texlive-latex-extra</code><br />
# <code>unzip</code><br />
<br />
<br />
'''To install all of these packages in one fell swoop''', first become root: <br />
$ sudo su<br />
[sudo] password for wwadmin: <wwadmin password><br />
<br />
and then run the command ('''obviously you want to use cut and paste''')<br />
# apt install apache2 cpanminus curl dvipng gcc git imagemagick libapache2-request-perl \<br />
libarchive-zip-perl libarray-utils-perl libcrypt-ssleay-perl libdancer-perl libdancer-plugin-database-perl \<br />
libdata-dump-perl libdatetime-perl libemail-address-xs-perl libemail-sender-perl \<br />
libexception-class-perl libextutils-xsbuilder-perl libfile-find-rule-perl-perl \<br />
libgd-perl libhttp-async-perl libhtml-scrubber-perl libiterator-perl libiterator-util-perl libjson-perl \<br />
liblocale-maketext-lexicon-perl libmime-tools-perl libmoox-options-perl libnet-ip-perl libnet-ldap-perl \<br />
libnet-oauth-perl libossp-uuid-perl libpadwalker-perl libpath-class-perl \<br />
libphp-serialization-perl libpod-wsdl-perl \<br />
libsoap-lite-perl libsql-abstract-perl libstring-shellquote-perl libtemplate-perl \<br />
libtext-csv-perl libtimedate-perl libuuid-tiny-perl libxml-parser-easytree-perl \<br />
libxml-parser-perl libxml-writer-perl make netpbm npm pdf2svg \<br />
preview-latex-style texlive texlive-latex-extra unzip<br />
<br />
If prompted, you can always accept the default (hit <code>&lt;Enter&gt;</code>). When the process finishes, enter<br />
# exit<br />
to return to a regular user.<br />
<br />
=== Installation of Other Perl Modules with cpanm ===<br />
<br />
We will use <code>cpanm</code> to install other perl modules. For example, one module, <code>Statistics::R::IO</code> that will be needed is not in a standard package. To install this<br />
<pre><br />
cpanm Statistics::R::IO<br />
</pre><br />
<br />
Below, we will determine other perl modules that will need to be installed with this method. <br />
<br />
== Apache2 Modules and mod perl ==<br />
<br />
The following loads needed apache modules.<br />
<br />
=== enabling info.conf and status.conf in Ubuntu ===<br />
<br />
We enable the info module. Acting as <code>root</code> in a terminal window enter<br />
$ sudo su<br />
[sudo] password for wwadmin: <wwadmin password><br />
# a2enmod info<br />
<br />
Next we make a copy of the configuration files we will be editing for safekeeping. <br />
<br />
# cd /etc/apache2/mods-available<br />
<br />
# cp info.conf info.conf.bak1<br />
# cp status.conf status.conf.bak1<br />
<br />
# exit<br />
$<br />
<br />
Now we will edit configuration files <code>info.conf</code> and <code>status.conf</code> to allow us to view information about the setup and performance of the web server. Note that this is not absolutely necessary but it can be very useful. You can use your favorite editor but we will give instructions assuming you are using <code>nano</code>. Note that you have to be root to edit these files. First we edit <code>info.conf</code><br />
<br />
$ cd /etc/apache2/mods-available<br />
$ sudo nano info.conf<br />
[sudo] password for wwadmin: <wwadmin password><br />
<br />
I suggest you allow access to server information from e.g. your department domain. To do this uncomment (i.e. remove the <code>#</code> from) <br />
Require ip 192.0.2.0/24<br />
and then replace <code>192.0.2.0/24</code> by <code>.math.yourschool.edu</code><br />
where of course you should edit <code>.math.yourschool.edu</code> appropriately. <br />
<br />
Then save the file and quit (press <code>^X</code>, <code>Y</code>, <code>&lt;Enter&gt;</code>).<br />
<br />
Now we edit <code>status.conf</code><br />
<br />
$ cd /etc/apache2/mods-available<br />
$ sudo nano status.conf<br />
[sudo] password for wwadmin: <wwadmin password><br />
<br />
Edit the <br />
#Require ip 192.0.2.0/24<br />
line just as you did for <code>info.conf</code>.<br />
Then save the file and quit. And restart Apache so that the above changes take effect<br />
<br />
$ sudo systemctl restart apache2<br />
password:<wwadmin password><br />
<br />
===Fully Qualified Domain Name=== <br />
Now we have to set your server's fully qualified domain name. Note that if your network was set up automatically via DHCP, your server's fully qualified domain name should already be set up. You can check by running the <code>hostname</code> commands below.<br />
<br />
Run the command <br />
sudo hostnamectl set-hostname webwork<br />
[sudo] password for wwadmin: <wwadmin password><br />
where of course you should replace webwork by whatever your server's name is.<br />
<br />
<br />
You can check these settings by running the commands<br />
<br />
$ hostname --fqdn<br />
and <br />
$ hostname<br />
<br />
The first gives the server's fully qualified domain name (e.g. webwork.mydepartment.myschool.edu) and the second the server's name (e.g. webwork).<br />
<br />
Note that if your server can not find its fully qualified domain name, certain tools (such as the Synaptic Package Manager) may not start.<br />
<br />
===Test Apache===<br />
Now restart Apache<br />
<br />
$ sudo systemctl restart apache2<br />
password:<wwadmin password><br />
or<br />
$ sudo apache2ctl restart<br />
[sudo] password for wwadmin: <wwadmin password><br />
or<br />
$ sudo service apache2 restart<br />
[sudo] password for wwadmin: <wwadmin password><br />
<br />
<br />
and test your server by connecting to your<br />
server ("http://yourserver.yourschool.edu") from a browser on a remote machine. You should see the '''Apache2 Ubuntu Default Page''' indicating that Apache is running.<br />
<br />
You can check Apache's status by connecting to<br />
"http://yourserver.yourschool.edu/server-status" from a browser on a remote machine in the math.yourschool.edu domain.<br />
<br />
Further test Apache by connecting to<br />
"http://yourserver.yourschool.edu/server-info" from a browser on a remote machine in the math.yourschool.edu domain and you will see a page listing various <br />
information about Apache. In particular under <code>Server Settings</code> you should see<br />
<br />
Server Version: Apache/2.4.41 (Ubuntu) mod_apreq2-20090110/2.8.0 mod_perl/2.0.11 Perl/v5.30.0<br />
(or something very similar) indicating that both <code>mod_apreq2</code> and <code>mod_perl</code> are installed.<br />
<br />
If you have problems now or in the future, a good first thing to do is to look at the Apache error log which is located at <code>/var/log/apache2/error.log</code>. In the directory <code>/var/log/apache2/</code> you can "less" through the error log (<code>less error.log</code>), look at the last few entries (<code>tail error.log</code>) or run the command <code>tail -f error.log</code> which will display new error messages as they are appended to the file. Use <br />
<code>^C</code> to break out of <code>tail -f</code> . For example if you didn't set up access to "server-info", you can run<br />
tail /var/log/apache2/error.log<br />
and in the output you should see something similar to<br />
...[mpm_event:notice] [pid 48932:tid 140494759132224] AH00489: Apache/2.4.41 (Ubuntu) mod_apreq2-20090110/2.8.0 mod_perl/2.0.11 Perl/v5.30.0 configured -- resuming normal operations<br />
indicating that both <code>mod_apreq2</code> and <code>mod_perl</code> are installed and running.<br />
<br />
== Installing a Database ==<br />
<br />
This section installs either MySQL or MariaDB as the database manger for webwork. It is recommended that MariaDB is used. There have been a few examples of connection issues with MySQL. <br />
<br />
<br />
=== Installing and Testing MariaDB ===<br />
<br />
Install MariaDB using the distro packages. <br />
<br />
$ sudo apt install mariadb-server libdbd-mariadb-perl<br />
<br />
<br />
=== Installing and Testing MySQL ===<br />
<br />
If you wish to use MySQL: <br />
<br />
$ sudo apt install mysql-server libdbd-mysql-perl<br />
<br />
=== Securing the Database ===<br />
<br />
Then we should secure the server<br />
<br />
$ sudo mysql_secure_installation<br />
[sudo] password for wwadmin: <wwadmin password><br />
<br />
You can setup the VALIDATE PASSWORD plugin if you wish. I chose not to.<br />
<br />
Next you will be asked to enter a<br />
<code>New password for the MySQL "root" user</code>. Enter your chosen MySQL <code>root</code> password. You have to enter a password but it will not be used. In Ubuntu systems running MySQL 5.7 (and later versions), the root MySQL user is set to authenticate using the auth_socket plugin by default rather than with a password. <br />
<br />
You almost certainly want to answer 'Y' to all questions '''except''' possibly for the first one which asks if you want to set up a VALIDATE PASSWORD plugin.<br />
Now test that all is well:<br />
<br />
$ sudo mysql <br />
[sudo] password for wwadmin: <wwadmin password><br />
<br />
You should see<br />
<br />
Welcome to the MySQL monitor ...<br />
mysql><br />
<br />
Now lets check the MySQL users.<br />
There are five accounts. To see the accounts, do the following <br />
<br />
mysql> SELECT user,authentication_string,plugin,host FROM mysql.user;<br />
<br />
You will see a table with five users (<code>debian-sys-maint</code>, <code>mysql.infoschema</code>, <code>mysql.session</code>, <code>mysql.sys</code> and <code>root</code>). <br />
You should see that one of the five users has a valid password (which will be displayed in encrypted form) and <code>root</code> is authenticated by a socket. You can ignore the <code>mysql.session</code>, <code>mysql.sys</code> and <code>mysql.infoschema</code> users.<br />
<br />
Now exit MySQL<br />
<br />
mysql> exit<br />
Bye<br />
$<br />
<br />
This last step is optional since currently most of WeBWorK's MySQL tables are now created using the MyISAM engine (by default -- this can be changed in the config files) rather than the MySQL default engine. Now we change MySQL's default engine. The default engine is InnoDB as of MySQL 5.5.5 (MyISAM before 5.5.5) but (at least on some hardware) InnoDB seems to be 50-100 times slower than MyISAM. So we will change the default MySQL engine from InnoDB to MyISAM. Note that this change only applies to new tables, tables already constructed will continue to use InnoDB. But we haven't created any WeBWorK tables so we don't have to change the engine for any existing tables.<br />
<br />
=== Changing the default MySQL/MariaDB engine ===<br />
<br />
To change the default MySQL engine from InnoDB to MyISAM do the following:<br />
<br />
$ cd /etc/mysql/mysql.conf.d<br />
$ sudo cp mysqld.cnf mysqld.cnf.bak1<br />
[sudo] password for wwadmin: <wwadmin password><br />
$ sudo nano mysqld.cnf<br />
<br />
Search for <code>[mysqld]</code> and under "Basic Settings" above the "user = mysql" line add the line<br />
default-storage-engine = myisam <br />
<br />
Then save the file and quit. Restart Mysql<br />
<br />
$ sudo /etc/init.d/mysql restart<br />
[sudo] password for wwadmin: <wwadmin password><br />
or<br />
$ sudo service mysql restart<br />
[sudo] password for wwadmin: <wwadmin password><br />
<br />
and log into mysql<br />
$ sudo mysql <br />
[sudo] password for wwadmin: <wwadmin password><br />
<br />
You will see<br />
<br />
Welcome to the MySQL monitor ...<br />
mysql><br />
<br />
If you show MySQL engines<br />
<br />
mysql> SHOW ENGINES\G<br />
<br />
you should see that MyISAM is listed as the default engine:<br />
...<br />
*************************** 5. row ***************************<br />
Engine: MyISAM<br />
Support: DEFAULT<br />
Comment: MyISAM storage engine <br />
Transactions: NO<br />
XA: NO<br />
Savepoints: NO<br />
<br />
Now exit<br />
mysql> exit<br />
Bye<br />
$<br />
<br />
== Downloading the WeBWorK System Software and Problem Libraries ==<br />
We are finally at the point where we can start downloading and installing WeBWorK. We will use Git to download WeBWorK from Github. This is easy and it will also make it easy to update the system in the future. Note that the following are rather long commands; it is much easier to copy (<code>^C</code>) them from this document and paste (<code>&lt;Shift&gt; &lt;Ctrl&gt; &lt;V&gt;</code><br />
or <code>&lt;Shift&gt; &lt;Insert&gt;</code>) them in a terminal window<br />
<br />
$ cd<br />
$ cd downloads<br />
$ git clone git://github.com/openwebwork/webwork2.git<br />
$ git clone git://github.com/openwebwork/pg.git<br />
$ git clone git://github.com/openwebwork/webwork-open-problem-library.git<br />
<br />
'''Important Note'''. The above commands retrieve the master branch which gives the latest stable release of the software package (webwork2, pg, etc.) with bug fixes. If a stable release newer than 2.15 exists, that will be downloaded and these instructions may be a little out of date. So it is a good idea to check before downloading. The best way to do that is to look at https://github.com/openwebwork/webwork2/blob/master/VERSION and https://github.com/openwebwork/pg/blob/master/VERSION.<br />
<br />
The first and second download gives you the latest released versions.<br />
The third download contains the WeBWorK Open Problem Library (OPL) which is the new name for the original National Problem Library (NPL). The NPL has been renamed to reflect its growing international content. Your system will be loaded with many thousands of WeBWorK problems (over 30,000 currently).<br />
<br />
The main information page about WebWork downloads is available at http://webwork.maa.org/wiki/Category:Release_Notes<br />
<br />
The main information page about the OPL is available at http://webwork.maa.org/wiki/Open_Problem_Library<br />
<br />
==Installing WeBWorK==<br />
<br />
'''Note the instructions below assume you are installing WeBWorK from scratch. If you are just upgrading WeBWorK, especially if you already have existing WeBWorK courses, see [[Upgrading WeBWorK]].'''<br />
<br />
=== Move the System into the Required Directories ===<br />
As <code>root</code> create a <code>webwork</code> directory under <code>/opt</code>, change the ownership of the <code>webwork</code> directory to <code>www-data</code>, which is what the apache server runs as and move directories there. <br />
<br />
$ cd<br />
$ cd downloads<br />
$ sudo mkdir /opt/webwork<br />
[sudo] password for wwadmin: <wwadmin password><br />
$ sudo chown www-data:www-data /opt/webwork<br />
$ mv webwork2 /opt/webwork/<br />
$ mv pg /opt/webwork/<br />
<br />
<br />
<br />
Now create the <code>courses</code> and <code>libraries</code> directories under <code>webwork</code> and copy and move content there <br />
<br />
$ mkdir /opt/webwork/courses<br />
$ mkdir /opt/webwork/libraries<br />
$ mv webwork-open-problem-library /opt/webwork/libraries/<br />
$ cd /opt/webwork/webwork2/courses.dist<br />
$ cp *.lst /opt/webwork/courses/<br />
$ rsync -a modelCourse /opt/webwork/courses/<br />
<br />
=== Setting Permissions ===<br />
<br />
The PG installation directory and files should be owned by <code>www-data</code> and not writable by other users:<br />
<br />
$ cd /opt/webwork/pg<br />
$ chmod -R u+rwX,go+rX .<br />
<br />
Most WeBWorK directories and files should also be owned by <code>www-data</code> and not writable by other users:<br />
<br />
$ cd /opt/webwork/webwork2<br />
$ chmod -R u+rwX,go+rX .<br />
<br />
Certain data directories need to be writable by the web server. These are <code>DATA</code>, <code>courses</code>, <code>htdocs/tmp</code>, <code>logs</code>, and <code>tmp</code>. It is convenient to give WeBWorK administrators access to these directories as well, so they can perform administrative tasks such as removing temporary files, creating and editing courses from the command line, managing logs, and so on. We will use the group <code>www-data</code>, containing both the WeBWorK administrators and the web server. Consider the user WWADMIN<br />
<br />
Run the command:<br />
$ sudo adduser WWADMIN www-data<br />
<br />
$ id WWADMIN<br />
<br />
and then you should see <code>wwdata</code> listed under groups. Also<br />
<br />
$ id www-data<br />
<br />
should show <code>www-data</code> listed under groups. <br />
<br />
Now we make the WeBWorK directories that need to be writable by the web server have <code>www-data</code> as their group. The following are rather long commands; you might want to copy them and paste them into your terminal window rather than typing them.<br />
<br />
$ sudo su<br />
[sudo] password for wwadmin: <wwadmin password><br />
# cd /opt/webwork/webwork2/<br />
# chgrp -R www-data DATA ../courses htdocs/tmp htdocs/applets logs tmp /opt/webwork/pg/lib/chromatic<br />
# chmod -R g+w DATA ../courses htdocs/tmp htdocs/applets logs tmp /opt/webwork/pg/lib/chromatic<br />
# find DATA/ ../courses/ htdocs/tmp logs/ tmp/ -type d -a -exec chmod g+s {} \;<br />
# exit<br />
$<br />
<br />
=== Compile color.c ===<br />
<br />
$ cd /opt/webwork/pg/lib/chromatic<br />
$ gcc color.c -o color<br />
<br />
You may see some warning messages which you can safely ignore.<br />
<br />
== Configuring the Shell ==<br />
<br />
To make working with WeBWorK easier, there are a couple of changes you can make to your shell environment.<br />
<br />
Add the WeBWorK <code>bin</code> directory to your path. This will allow you to run WeBWorK command-line utilities without typing the full path to the utility. Goto your home directory and backup your <code>.bashrc</code> file<br />
<br />
$ cd<br />
$ cp .bashrc .bashrc.bak1<br />
<br />
Now edit <code>.bashrc</code><br />
<br />
$ nano .bashrc<br />
<br />
After the last line add the three lines:<br />
<br />
export PATH=$PATH:/opt/webwork/webwork2/bin<br />
export WEBWORK_ROOT=/opt/webwork/webwork2<br />
export PG_ROOT=/opt/webwork/pg<br />
<br />
Then save the file and Quit.<br />
<br />
Close your Terminal Window and open a new one so the above changes<br />
take effect. You can check that they have by<br />
<br />
$ echo $PATH<br />
$ echo $WEBWORK_ROOT<br />
$ echo $PG_ROOT<br />
<br />
== Checking Module Dependencies ==<br />
<br />
WeBWorK includes a script called <code>check_modules.pl</code> (in the directory <code>/opt/webwork/webwork2/bin</code>) that verifies that the needed programs and Perl modules are installed on your system. Run this script to make sure you have installed the required programs and Perl modules.<br />
<br />
$ check_modules.pl apache2<br />
<br />
Scroll up and look through the listing. It should find everything. If something is missing (flagged by <code>**</code>), look back through these instructions to find where it should have been installed and install it. <br />
<br />
You may see some warning messages like <br />
Prototype mismatch: sub main::from_json: none vs ($@) at (eval 188) line 2.<br />
Prototype mismatch: sub main::to_json: none vs ($@) at (eval 188) line 2.<br />
This is a known bug in libjson-perl and can be safely ignored.<br />
<br />
A common perl package that isn't installed is <code>Statistics::R::IO</code>. It can be installed with<br />
<br />
$ cpanm Statistics::R::IO<br />
<br />
which will install any needed dependencies and run tests. <br />
<br />
=== Obtaining Javascript Libraries ===<br />
<br />
Javascript libraries are now obtained using <code>npm</code>. This includes the following javascript packages:<br />
<br />
# <code>codemirror</code><br />
# <code>fontawesome</code><br />
# <code>iframe-resizer</code><br />
# <code>jQuery</code><br />
# <code>jQuery-ui</code><br />
# <code>MathJax</code><br />
# <code>nestedSortable</code><br />
<br />
To install all of these: <br />
<br />
$ cd /opt/webwork/webwork2/htdocs/<br />
$ npm install<br />
<br />
=== Checking LaTeX packages ===<br />
<br />
Now we check that all necessary LaTeX packages have been installed. Run the commands<br />
$ cd<br />
$ pdflatex /opt/webwork/webwork2/bin/check_latex.tex<br />
and look for missing packages (you can ignore "No file check_latex.aux.").<br />
<br />
== Configuring WeBWorK ==<br />
<br />
=== Making Copies of the Distribution Configuration Files ===<br />
<br />
Before configuring the system, you must make local copies of the <code>site.conf</code> and <code>localOverrides.conf</code> configuration files, located in <code>/opt/webwork/webwork2/conf/</code> . <br />
<br />
$ cd /opt/webwork/webwork2/conf<br />
$ cp site.conf.dist site.conf<br />
$ cp localOverrides.conf.dist localOverrides.conf<br />
<br />
=== System 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 instructors 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 />
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 />
==== Edit the site.conf file ====<br />
Now edit <code>site.conf</code><br />
<br />
$ cd /opt/webwork/webwork2/conf<br />
$ nano site.conf<br />
<br />
First we have to add information about the Apache2 server setup. <br />
Search for <code>server_root_url</code> and edit the line so that it reads:<br />
<br />
$server_root_url = 'http://yourserver.yourschool.edu';<br />
<br />
where of course you should edit <code>yourserver.yourschool.edu</code> appropriately. The "http://" is important. '''If you are running a secure server (i.e., using SSL - really TLS), the url should start with https:<br />
but you should wait to make that change until after WeBWorK is up and running and you set up SSL. In that case the "https://" is important.<br />
<br />
=== Database Settings ===<br />
<br />
Search for the code <code>$database_driver</code>. Uncomment the type of database you set up (MySQL or MariaDB) and comment out the other. <br />
<br />
We need to set a password that WeBWorK uses when it communicates with the MySQL database. Note that this is not the same as the <code>&lt;mysql root password&gt;</code> which is the unused password we set when securing MySQL.<br />
Search for <code>database_password</code> and replace the line<br />
$database_password = "passwordRW";<br />
by <br />
$database_password = 'database_password';<br />
where of course you should replace "database_password" with your own password but do use the single quotes. Remember this password as we will need it below.<br />
<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 />
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 />
'''Note:''' Some servers will need to set a value of <code>$server_apache_version</code> in <code>site.conf</code>. This setting is needed when the Apache settings disable the display of the Apache version number in Apache banner of the HTTP headers, typically by setting <code>ServerTokens Prod</code> in the Apache cponfig, as many security teams will recommend. In such cases, without a setting for this variable, WeBWorK will fail to detect that you are using Apache 2.4 and users will run into error pages reporting <code>Can't locate object method "remote_addr" via package "Apache2::Connection" at /opt/webwork/webwork2/lib/WeBWorK/Authen.pm</code> which will also appear in the Apache error.log file. The fix is to search for <code>$server_apache_version</code>, uncomment the line, and set a suitable value (currently "2.4" should work, and a fix to support settings like "2.4.29" is pending).<br />
<br />
Then save the file and Quit.<br />
<br />
=== Default Header Files ===<br />
<br />
After you have used WeBWorK for awhile, you may want to change the default header files in <code>defaults.config</code>. Search for <code>$webworkFiles{screenSnippets}{setHeader}</code> and <code>$webworkFiles{hardcopySnippets}{setHeader}</code> in <code>localOverrides.config</code>. Settings in the conf and config files affect all WeBWorK courses. You can override any setting in these conf and config files for an individual course by putting the local setting in <code>course.conf</code>.<br />
<br />
Also now there are several versions of the classlist editor, homeworkset editor, library browser and pgproblem editor. Which ones are available in a course is determined by the settings for <code>%showeditors</code> in localOverrides.conf. As above, if you want to customize what is available for an individual course (e.g. one professor may want to try out the new editors and others may not), copy the <code>%showeditors</code> structure to <code>course.conf</code> and then edit it to make available the desired editors.<br />
<br />
=== Set up the webwork database ===<br />
<br />
WeBWorK uses a single database, called <code>webwork</code>, for all courses. We will create the <code>webwork</code> database now.<br />
<br />
To do this do the following ('''before you just copy, paste and hit <code>&lt;Enter&gt;</code>''' notice that you have to replace <code>database_password</code> with the password you set when editing <code>site.conf</code> above):<br />
<br />
$ sudo mysql <br />
[sudo] password for wwadmin: <wwadmin password><br />
<br />
mysql> CREATE DATABASE webwork;<br />
mysql> CREATE USER 'webworkWrite'@'localhost' IDENTIFIED BY 'database_password';<br />
mysql> GRANT SELECT, INSERT, UPDATE, DELETE, CREATE, ALTER, DROP, LOCK TABLES ON webwork.* TO 'webworkWrite'@'localhost';<br />
mysql> exit<br />
Bye<br />
$ <br />
<br />
where as we said '''replace''' <code>database_password</code> with the password you set when editing <code>site.conf</code> above.<br />
<br />
=== Configuring Apache ===<br />
WeBWorK ships with an Apache config file that needs to linked into your Apache configuration process. The file is named <code>webwork.apache2.4-config.dist</code> and located in the <code>conf</code> directory. First, copy the file to <code>webwork.apache2-config</code>:<br />
<br />
$ cd /opt/webwork/webwork2/conf<br />
$ cp webwork.apache2.4-config.dist webwork.apache2.4-config<br />
<br />
and now link it into your Apache configuration process<br />
<br />
$ sudo su<br />
[sudo] password for wwadmin: <wwadmin password><br />
# cd /etc/apache2/conf-enabled<br />
# ln -s /opt/webwork/webwork2/conf/webwork.apache2.4-config webwork.conf<br />
<br />
The default multi-processing module (MPM) for Apache is the event module but WeBWorK uses the prefork module. So we disable the event module and enable the prefork module.<br />
<br />
# a2dismod mpm_event<br />
# a2enmod mpm_prefork<br />
<br />
Next we will make a few changes to Apache's default configuration. We need to edit two files. First we will<br />
save copies of the original files. <br />
# cd /etc/apache2/<br />
# cp apache2.conf apache2.conf.bak1<br />
# cd /etc/apache2/mods-available/<br />
# cp mpm_prefork.conf mpm_prefork.conf.bak1<br />
# exit<br />
<br />
====Edit apache2.conf====<br />
<br />
$ cd /etc/apache2/<br />
$ sudo nano apache2.conf<br />
<br />
Search for the line<br />
Timeout 300<br />
and replace it by<br />
Timeout 1200 <br />
<br />
Then save the file and quit. <br />
<br />
====Edit mpm_prefork.conf====<br />
<br />
$ cd /etc/apache2/mods-available/<br />
$ sudo nano mpm_prefork.conf<br />
<br />
Search for the lines<br />
MaxRequestWorkers 150<br />
MaxConnectionsPerChild 0<br />
Which occur under <code><IfModule mpm_prefork_module></code> and replace them by<br />
# For WeBWorK a rough rule of thumb is 5 MaxRequestWorkers per 1 GB of memory<br />
MaxRequestWorkers 10<br />
MaxConnectionsPerChild 50<br />
where you should set <code>MaxRequestWorkers</code> depending on the amount of memory your server has using the above rule of thumb. Note that for <br />
very busy servers, you should observe you memory usage and adjust the above settings as necessary. Also make sure MaxSpareServers is not set too high.<br />
<br />
Then save the file and quit.<br />
<br />
Finally we copy WeBWorK's icon file <code>favicon.ico</code> to Apache's <code>www</code> directory.<br />
$ sudo cp /opt/webwork/webwork2/htdocs/favicon.ico /var/www/html<br />
[sudo] password for wwadmin: <wwadmin password><br />
<br />
Now stop and start Apache. We do it this way to make sure the MPM gets changed. <br />
<br />
$ sudo apache2ctl stop<br />
[sudo] password for wwadmin: <wwadmin password><br />
$ sudo apache2ctl start<br />
<br />
== Test your configuration ==<br />
<br />
# Test the <code>/webwork2</code> location by visiting <code>http://yourserver.yourschool.edu/webwork2</code>. You should see the WeBWorK home page with no courses listed. Actually the directory <code>/opt/webwork/courses/</code> does contain the <code>modelCourse</code> but the <code>modelCourse</code> is not a real course so you will get an error message if you try to log into it. It will be used a as model for setting up other courses. For this reason <code>/opt/webwork/courses/modelCourse/</code> contains a file named <code>hide_directory</code> and so the <code>modelCourse</code> is not visible.<br />
# Test the <code>/webwork2_files</code> location by visiting <code>http://yourserver.yourschool.edu/webwork2_files</code>. You should see the "WeBWorK Placeholder Page".<br />
# You cannot test the <code>/webwork2_course_files</code> location until you have created a course.<br />
<br />
==If Something is Wrong ==<br />
If something is wrong one of the first things to check is that the config files have been edited correctly (e.g. one time a wrapped line in <code>localOverrides.conf</code> caused me problems, another time it was a missing single quote). A quick way to check this is to do a <code>diff</code> between the edited and distributed versions and check that <code>diff</code> reports the changes you made and only those. Another thing is to look at the Apache error log which is located at <code>/var/log/apache2/error.log</code>.<br />
<br />
$ cd /etc/apache2/<br />
$ diff apache2.conf apache2.conf.bak1<br />
$ cd /opt/webwork/webwork2/conf/<br />
$ diff site.conf site.conf.dist<br />
$ diff localOverrides.conf localOverrides.conf.dist<br />
$ diff webwork.apache2.4-config webwork.apache2.4-config.dist<br />
$ tail /var/log/apache2/error.log <br />
<br />
If something is wrong and you fix it, you will have to restart Apache for the changes to take effect<br />
<br />
$ sudo service apache2 restart<br />
[sudo] password for wwadmin: <wwadmin password><br />
<br />
== Create the admin Course ==<br />
<br />
[[Course Administration]] gives information about creating courses. Here we will give explicit instructions for doing this. (You may need to become root or use sudo to execute some of these commands.)<br />
<br />
$ cd /opt/webwork/courses<br />
$ /opt/webwork/webwork2/bin/addcourse admin --db-layout=sql_single --users=adminClasslist.lst --professors=admin<br />
$ sudo chown -R www-data:www-data admin <br />
[sudo] password for wwadmin: <wwadmin password><br />
<br />
where the last line makes the course <code>admin</code> and its subdirectories owned by the Apache server and readable/writeable by the WWADMIN user.<br />
<br />
Now goto <code>http://yourserver.yourschool.edu/webwork2</code> and should see the WeBWorK home page with <code>Course Administration</code> listed at the top. Click on it and login with Username <code>admin</code> and Password <code>admin</code> . This first thing you should do is register your new WeBWorK installation. It's quick and easy, just click on <code>Register</code>. '''IMPORTANT''' The next thing you should do is click on <code>User Settings</code> and change <code>admin</code> 's password to something more secure than <code>admin</code> . <br />
<br />
Unless you choose otherwise, users with <code>admin</code> privileges in the <code>admin</code> course (i.e. WeBWorK administrators) will automatically be added to new courses with <code>admin</code> privileges and the same password as in the <code>admin</code> course. Initially the only such user is <code>admin</code> (hopefully you are not confused by the fact that the course <code>admin</code> has a user named <code>admin</code>). It's usually convenient make yourself a WeBWorK administrator. To do this (assuming you are logged in as <code>admin</code> to the <code>admin</code> course at <code>http://yourserver.yourschool.edu/webwork2/admin</code> )<br />
# Click on <code>Classlist Editor</code> in the left panel<br />
# Click the <code>Add</code> tag and click <code>Take Action!</code><br />
# Enter the appropriate information (you can use your <code>Login Name</code> as the <code>Student ID</code> if you want and also you can leave the last three items blank) and click <code>Add Students</code><br />
# Click on <code>Classlist Editor</code> in the left panel again<br />
# When you enter a new student, by default their <code>Student ID</code> is used as their password. We'll change this now.<br />
# Select yourself with a check mark and click the <code>Password</code> tag and click <code>Take Action!</code>. (Note as a safely mechanism you can not change the password for the user you are logged in as, currently <code>admin</code>, this way) <br />
# Enter the password and then click <code>Take Action!</code><br />
# Finally give yourself <code>admin</code> privileges by selecting yourself with a check mark, clicking the <code>Edit</code> tag and then clicking <code>Take Action!</code> (or by just clicking on the "pencil" next to your login name which is a much faster way to edit classlist data for a single user)<br />
# Now at the far right change <code>Permission Level</code> from <code>student</code> to <code>admin</code><br />
# Then click <code>Take Action!</code><br />
<br />
At some point you will probably want to hide the <code>admin</code> course so that it is not listed on the WeBWorK home page. As we noted above the <code>modelCourse</code>, which is already hidden, is not a real course so you will get an error message if you try to log into it. This is a good reason to hide it. The <code>modelCourse</code> is very useful as a model (hence its name) for setting up other courses. The <code>admin</code> course is used for administering WeBWorK and even though regular users can not log into it (you did change the <code>admin</code> password, didn't you!!), it a little bit cleaner and safer to hide it from prying eyes. <br />
To hide (or unhide) a course select <code>Hide Inactive courses</code> in the admin course and follow the directions. When hidden a course will not show up in the courses list on the WeBWorK home page. It will still appear in the Course Administration listing. If you do this you will still be able to access the <code>admin</code> course using the URL <code>http://yourserver.yourschool.edu/webwork2/admin</code> but you will not see a link for it on the WeBWorK home page <code>http://yourserver.yourschool.edu/webwork2</code> . <br />
<br />
<br />
Now goto <code>http://yourserver.yourschool.edu/webwork2</code> and no course will be listed.<br />
<br />
==Checking for and Installing Hotfixes==<br />
<br />
The following commands show you how to check for and install bug fixes. '''Important Note:''' These commands check and retrieve the master branch which gives the latest stable release of the software package (webwork2, pg, etc.) with bug fixes. If a stable release newer than 2.15 exists for webwork2 and/or pg, that will be checked and retrieved which is probably not what you want. Please check before updating. The best way to do that is to look at https://github.com/openwebwork/webwork2/blob/master/VERSION and https://github.com/openwebwork/pg/blob/master/VERSION.<br />
<br />
To check if there are bug fixes, do the following. <br />
===Updating the webwork2 code===<br />
<br />
First we check for updates to the webwork2 code:<br />
cd /opt/webwork/webwork2/<br />
git remote show origin<br />
This will print several lines of data, but the last line will tell you if your copy is up to date or out of date. If it is out of date, run<br />
git pull origin and restart apache2.<br />
<br />
===Updating the pg code===<br />
<br />
Now check for updates to the pg code:<br />
cd /opt/webwork/pg/<br />
git remote show origin<br />
This will print several lines of data, but the last line will tell you if your copy is up to date or out of date. If it is out of date, run<br />
git pull origin<br />
and restart apache2.<br />
<br />
===Restart apache2===<br />
<br />
'''Important:''' After updating either webwork2 or pg, you have to restart apache2<br />
$ sudo apache2ctl restart<br />
password:<wwadmin password><br />
<br />
===Updating the OPL===<br />
<br />
The following assumes you have already installed the OPL. For that see [[#Install the Open Problem Library]] below.<br />
Now check for updates to the Open Problem Library:<br />
cd /opt/webwork/libraries/webwork-open-problem-library<br />
git remote show origin<br />
This will print several lines of data, but the last line will tell you if your copy is up to date or out of date. If it is out of date, run<br />
git pull origin<br />
Then rerun the <code>OPL-update</code> script. Updating the OPL is pretty much risk free since changes usually involve only a relatively small <br />
number of individual problems and the vast majority of problems remain unchanged. Updating the OPL does not require restarting apache2.<br />
<br />
$ OPL-update<br />
<br />
== Starting and Stopping Apache and MySQL ==<br />
If you make changes to the system, you will have to restart <code>apache2</code> before the changes take effect. On rare occasions you may need to restart <code>MySQL</code>. <br />
=== Starting and Stopping Apache ===<br />
You have to run these commands as <code>root</code>.<br />
<br />
To start or restart (i.e. stop and then start) the <code>apache2</code> webserver run the command <br />
$ sudo apache2ctl graceful<br />
[sudo] password for wwadmin: <wwadmin password><br />
You can also start <code>apache2</code> by<br />
$ sudo apache2ctl start<br />
[sudo] password for wwadmin: <wwadmin password><br />
and restart it with<br />
$ sudo apache2ctl restart<br />
[sudo] password for wwadmin: <wwadmin password><br />
<code>restart</code> is less graceful but more powerful than <code>graceful</code>. Sometimes <code>graceful</code> fails to kill all <code>apache2</code> child processes. <br />
<br />
<br />
To stop the Apache webserver run the command <br />
<br />
$ sudo apache2ctl stop<br />
[sudo] password for wwadmin: <wwadmin password><br />
<br />
Stopping and then starting Apache should definitely kill all <code>apache2</code> child processes. <br />
<br />
You can also start or stop apache2 by using the <code>init.d</code> script <code>apache2</code>. Run<br />
$ sudo /etc/init.d/apache2<br />
[sudo] password for wwadmin: <wwadmin password><br />
or equivalently<br />
$ sudo service apache2<br />
[sudo] password for wwadmin: <wwadmin password><br />
<br />
and you will get a list of allowed commands (<code>start</code>, <code>stop</code>, <code>restart</code>, etc.).<br />
<br />
Finally you can use the newer <code>systemctl</code> method, e.g.<br />
sudo systemctl start apache2<br />
[sudo] password for wwadmin: <wwadmin password><br />
<br />
sudo systemctl --help <br />
will give you a list of all possible commands, the main ones being <code>start</code>, <code>stop</code>, <code>restart</code> and <code>status</code>.<br />
<br />
=== Starting and Stopping MySQL===<br />
You have to run these commands as <code>root</code>.<br />
<br />
To start the <code>MySQL</code> server run the command <br />
<br />
$ /etc/init.d/mysql start<br />
<br />
To stop the <code>MySQL</code> server run the command <br />
$ sudo /etc/init.d/mysql stop<br />
<br />
To restart the <code>MySQL</code> server run the command <br />
$ sudo /etc/init.d/mysql restart<br />
<br />
<br />
Equivalently you can use the command<br />
$ systemctl start mysql <br />
<br />
and <code>start</code> can be replaced by <code>stop</code> and <code>restart</code>. Also, <br />
<br />
$ systemctl status mysql <br />
<br />
gives information about the mysql server. <br />
<br />
$ systemctl --help <br />
will give you a list of all possible commands.<br />
<br />
=== Starting and Stopping MariaDB ===<br />
You have to run these commands as <code>root</code>.<br />
<br />
To start the <code>MariaDB</code> server run the command <br />
<br />
$ /etc/init.d/mysql start<br />
<br />
To stop the <code>MariaDB</code> server run the command <br />
$ sudo /etc/init.d/mysql stop<br />
<br />
To restart the <code> MariaDB </code> server run the command <br />
$ sudo /etc/init.d/mysql restart<br />
<br />
<br />
Equivalently you can use the command<br />
$ systemctl start mariadb <br />
<br />
and <code>start</code> can be replaced by <code>stop</code> and <code>restart</code>. Also, <br />
<br />
$ systemctl status mariadb <br />
<br />
gives information about the mysql server. <br />
<br />
$ systemctl --help <br />
will give you a list of all possible commands.<br />
<br />
<br />
==Install the WeBWorK Problem Libraries ==<br />
Before we create a real course we will install the WeBWorK Problem Libraries.<br />
<br />
===Install the Open Problem Library ===<br />
The <code>Open Problem Library</code> consists of both WeBWorK problems and methods for searching and selecting problems. Also it contains as sub libraries many of the other standard libraries. We have to load a database for searching it.<br />
<br />
First we put a link to the Open Problem Library in the modelCourse so that when we create courses copying templates from the modelCourse, the OPL will be available.<br />
<br />
$ cd /opt/webwork/courses/modelCourse/templates/<br />
$ ln -s /opt/webwork/libraries/webwork-open-problem-library/OpenProblemLibrary Library<br />
<br />
Note that if the above link is not in the templates directory of a course, it will be automatically created when you open the Library Browser. However, <br />
if e.g. you haven't yet opened the Library Browser and the link is missing and you import problem sets (as we do in section [[#Test that Things are Working Properly|Test that Things are Working Properly]] below), you may see errors <br />
when viewing problems (you definitely will see errors in the Orientation set).<br />
<br />
Next we have to run the <code>OPL-update</code> script which will create the data that the Library Browser uses.<br />
<br />
$ OPL-update<br />
<br />
This has to convert a lot of data for over 37,000 problems so please be patient; it can take a long time.<br />
<br />
If at some time in the future you want to upgrade the Problem Library, the process<br />
is easy, see [[#Updating the OPL|Updating the OPL]]. Note that this is something you should do fairly often so that your library is up to date with<br />
new problems and bug fixes for old ones.<br />
<br />
===Initialize the OPL local statistics database table===<br />
Run the command<br />
$ update-OPL-statistics.pl<br />
to create a table to hold the OPL local statistics. See https://webwork.maa.org/wiki/OPL_Problem_Statistics for information.<br />
<br />
===Set up the access to the Contrib directory ===<br />
<br />
The <code>Contrib</code> directory contains contributions to the OPL that may not have been formally accepted into the main collection of OPL problems. This may be because the contribution is recent and has not yet been reviewed or because the problems are not properly tagged as is the case with the CAPA problem collection. It also contains the original versions of problems that have been accepted into the OPL (the idea being that the original authors maintain control of problems in the <code>Contrib</code> directory but problems in the OPL are controled by the editors). This step creates a button in the Library Browser which gives a direct link to the <code>Contrib</code> directory.<br />
<br />
<br />
Put a link to the Contrib directory in the <code>modelCourse</code> so that when we create courses copying templates from the <code>modelCourse</code>, the Contrib directory will be available. <br />
<br />
$ cd /opt/webwork/courses/modelCourse/templates/<br />
$ ln -s /opt/webwork/libraries/webwork-open-problem-library/Contrib Contrib<br />
<br />
If you just want to do this for individual courses, not all courses then don't put the link in the <code>modelCourse</code> above, and then do the following. Note we don't have any individual courses yet. But for example after creating <code>myTestCourse</code> below, to set up access to the <code>Contrib</code> directory from <code>myTestCourse</code>, do the following<br />
$ cd /opt/webwork/courses/myTestCourse/templates/<br />
$ sudo $ ln -s /opt/webwork/libraries/webwork-open-problem-library/Contrib Contrib<br />
[sudo] password for wwadmin: <wwadmin password><br />
<br />
===Set up the Rochester and Union Libraries ===<br />
<br />
This step is optional. It creates buttons in the Library Browser which give direct links to the Rochester and Union libraries. If you don't do this, you can find these libraries and others under the <code>OPL Directory</code> button.<br />
<br />
First we need to edit <code>localOverrides.conf</code> one last time<br />
<br />
$ cd /opt/webwork/webwork2/conf<br />
$ nano localOverrides.conf<br />
<br />
Search for <code>courseFiles{problibs}</code> and scroll down several lines to the lines<br />
# rochesterLibrary =&gt; "Rochester",<br />
# unionLibrary =&gt; "Union",<br />
Uncomment these lines (i.e. remove the <code>#</code>) so they become <br />
rochesterLibrary =&gt; "Rochester",<br />
unionLibrary =&gt; "Union",<br />
Then save the file and quit.<br />
<br />
We next put links to the Rochester and Union Libraries in the <code>modelCourse</code> so that when we create courses copying templates from the <code>modelCourse</code>, these libraries will be available. Skip this step if you usually only want to use Open Problem Library. Note that the Rochester, Union and other libraries are contained in the OPen Problem Library and are accessible from there under the <code>OPL Directory</code> button in the Library Browser. This step simply creates buttons in the Library Browser so that you can access the Rochester and Union libraries directly.<br />
<br />
$ cd /opt/webwork/courses/modelCourse/templates/<br />
$ ln -s /opt/webwork/libraries/webwork-open-problem-library/OpenProblemLibrary/Union unionLibrary<br />
$ ln -s /opt/webwork/libraries/webwork-open-problem-library/OpenProblemLibrary/Rochester rochesterLibrary<br />
<br />
If you want to put another library into the <code>modelCourse</code>, just do the analogous thing. If you just want the additional library in a particular course, add the link in the <code>templates</code> directory of that course. If you look in the directory <code>/opt/webwork/libraries/webwork-open-problem-library/OpenProblemLibrary/</code> you might find other libraries that are not yet listed in <code>global.conf</code> and these can be added in the same way as the <code>Rochester and </code><code>Union</code> libraries. Finally if you add a library with non standard symbols in the name (e.g. <code>uva-statLibrary</code>) you have to use single quotes when adding it to <code>global.conf</code>, e.g. <br><br />
&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp; <code>'uva-statLibrary' => "UVA-Stat",</code> <br><br />
It's easier to just avoid such names.<br />
<br />
===Install and Set Up the CAPA Library ===<br />
<br />
This step is optional. It installs and sets up [[CAPA Physics Problems|the CAPA Library]], which is a library of physics problems.<br />
<br />
'''Note:''' We are in the process of integrating the CAPA problems into the main distribution so some of the details below may change.<br />
<br />
Move the CAPA graphics files to the required locations and set the group.<br />
<br />
$ cd /opt/webwork/libraries/webwork-open-problem-library/Contrib/CAPA <br />
$ mv CAPA_Graphics /opt/webwork/webwork2/htdocs/<br />
$ sudo chgrp -R wwdata /opt/webwork/webwork2/htdocs/CAPA_Graphics<br />
[sudo] password for wwadmin: <wwadmin password><br />
$ sudo chmod -R g+w /opt/webwork/webwork2/htdocs/CAPA_Graphics <br />
<br />
We need to edit <code>localOverrides.conf</code> again<br />
<br />
$ cd /opt/webwork/webwork2/conf<br />
$ nano localOverrides.conf<br />
<br />
<br />
Now search for the lines<br />
$pg{specialPGEnvironmentVars}{CAPA_Tools} = "$courseDirs{templates}/Contrib/CAPA/macros/CAPA_Tools/",<br />
$pg{specialPGEnvironmentVars}{CAPA_MCTools} = "$courseDirs{templates}/Contrib/CAPA/macros/CAPA_MCTools/",<br />
$pg{specialPGEnvironmentVars}{CAPA_GraphicsDirectory} = "$courseDirs{templates}/Contrib/CAPA/CAPA_Graphics/",<br />
push @{$pg{directories}{macrosPath}},<br />
"$courseDirs{templates}/Contrib/CAPA/macros/CAPA_Tools",<br />
"$courseDirs{templates}/Contrib/CAPA/macros/CAPA_MCTools";<br />
<br />
and replace these six lines by<br />
<br />
################################################################################<br />
#Locations of CAPA resources. (Only necessary if you need to use converted CAPA problems.)<br />
################################################################################<br />
$pg{specialPGEnvironmentVars}{CAPA_Tools} = "$courseDirs{templates}/Contrib/CAPA/macros/CAPA_Tools/",<br />
$pg{specialPGEnvironmentVars}{CAPA_MCTools} = "$courseDirs{templates}/Contrib/CAPA/macros/CAPA_MCTools/",<br />
$pg{specialPGEnvironmentVars}{CAPA_GraphicsDirectory} = "$webworkDirs{htdocs}/CAPA_Graphics/";<br />
$pg{specialPGEnvironmentVars}{CAPA_Graphics_URL} = "$webworkURLs{htdocs}/CAPA_Graphics/";<br />
<br />
<br />
<br />
<br />
Then save the file and Quit.<br />
<br />
There is one final step that is needed. We have to put a link in the templates directory of every course that needs access to the CAPA Library. If you want to have every course you create have access to the CAPA Library (unlikely unless you are in a physics department) put the link in the <code>modelCourse</code>. <br />
$ cd /opt/webwork/courses/modelCourse/templates/<br />
$ ln -s /opt/webwork/libraries/webwork-open-problem-library/Contrib/CAPA/ capaLibrary<br />
<br />
More likely if you just want to do this for individual courses, not all courses then don't put the link in the <code>modelCourse</code> above, and then do the following. We don't have any yet. But for example after creating <code>myTestCourse</code> below, to set up access to the CAPA Library from <code>myTestCourse</code>, do the following<br />
$ cd /opt/webwork/courses/myTestCourse/templates/<br />
$ sudo ln -s /opt/webwork/libraries/webwork-open-problem-library/Contrib/CAPA/ capaLibrary<br />
[sudo] password for wwadmin: <wwadmin password><br />
<br />
<br />
and do the analogous thing for every course that needs access to the CAPA Library.<br />
Then to gain access to the CAPA Library from the course, simply go to the <code>Library Browser</code> and click on the <code>CAPA</code> button.<br />
<br />
<br />
<br />
==Create Your First Actual Course ==<br />
<br />
Since we have edited <code>site.conf</code> and <code>localOverrides.conf</code> and these are critical files, it would be a good idea to run<br />
$ cd /opt/webwork/webwork2/conf<br />
$ diff site.conf site.conf.dist<br />
$ diff localOverrides.conf localOverrides.conf.dist<br />
<br />
and check that you haven't made any mistakes (e.g. by introducing an inadvertent line break, etc.). If there are any mistakes, correct them. Remember that any time you change either of these files you must restart the Apache webserver in order for these changes to take effect. <br />
<br />
Since we have edited <code>global.conf</code> and haven't restarted Apache we do so now.<br />
$ sudo apache2ctl graceful<br />
password:<wwadmin password><br />
<br />
Now log into the <code>admin</code> course ( <code>http://yourserver.yourschool.edu/webwork2/admin</code> or, if you have not hidden the admin course, click on <code>Course Administration</code> on WeBWorK's home page <code>http://yourserver.yourschool.edu/webwork2/</code> ) as yourself or <code>admin</code> and <br />
# click on <code>Add Course</code><br />
# For <code>Course ID</code> enter <code>myTestCourse</code><br />
# For <code>Course Title</code> enter <code>My Test Course</code><br />
# Enter your institution<br />
# Leave <code>Add WeBWorK administrators to new course</code> checked<br />
# Add an additional instructor if you wish<br />
# Copy templates from: <code>modelCourse</code> (the default action)<br />
# Click on <code>Add Course</code><br />
# Click <code>Log into myTestCourse</code><br />
<br />
and log in either as <code>admin</code> or yourself (if you added yourself as an additional instructor above).<br />
<br />
At some point you will probably want to "hide" <code>myTestCourse</code> from general view but you already know how to do that.<br />
<br />
==Test that Things are Working Properly ==<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>.<br />
<br />
Click on <code>Hmwk Sets Editor</code> on the <code>Main Menu</code>. Then select <code>Import</code>, select <code>setDemo.def</code> from the <code>from</code> drop down list and select <code>all current users</code> from the <code>assigning this set to</code> drop down list. Then hit <code>Take Action!</code><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. If not, edit the file <code>Constants.pm</code> in the directory <code>/opt/webwork/webwork2/lib/WeBWorK</code>. Change the line <code>$WeBWorK::PG::ImageGenerator::PreserveTempFiles = 0;</code> to <code>...::PreserveTempFiles = 1;</code>. Then restart Apache and view the first couple problems or some new ones. Then look in the directory <code>/opt/webwork/webwork2/tmp/</code>. <code>cd</code> to one of the <code>ImageGenerator.../tmp/</code> directories and look at the error and log files there. When you fix the problem remember to edit <code>...::PreserveTempFiles = 1;</code> back to 0 and restart Apache or you will be saving a lot of unnecessary files. Another useful trick is to try downloading a hard copy of an assignment and then (assuming there are errors) looking at the various log files that are linked to on the output page.<br />
<br />
Note that since you probably used "admin" to login you have Permission Level "admin" so things look more complicated than if you were just a regular professor with Permission Level "professor". In particular any time you view a problem, you have the option to "Edit tags" which you probably do not want to do. If these bothers you, login as a professor (see below).<br />
<br />
Continue looking at problems to see if everything is working properly.<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 an admin 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>. If you get an error (you shouldn't) just click <code>Download Hardcopy</code> to get what was generated. Also you can see links to various informational files that are available if you run into problems (normally these files are removed if there are no errors). If you want to preserve these tmp files, set <code>$WeBWorK::ContentGenerator::Hardcopy::PreserveTempFiles</code><br />
to 1 in the file <code>Constants.pm</code> in the directory <code>/opt/webwork/webwork2/lib/WeBWorK</code> and then restart Apache. Remember to set this back to 0 after debugging.<br />
<br />
Another thing to do is to use <code>Email</code> on the <code>Main Menu</code>. Again this page is a little complicated because you can do a lot of things with it (including mail merge) but at this point just select yourself in the list to the right and hit <code>Send Email</code> at the bottom. You should receive two emails. One is the message you just sent and the other is an email with subject "WeBWorK email sent" giving information on your mailing. <br />
<br />
As a final test 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. You can also test that you can access any additional Problem Libraries that you installed. Note that if you just happen to view some statistics problems that require the R server, you will get errors (since we have not installed R --- at least not yet).<br />
<br />
'''Note:''' if when using the <code>Library Browser</code> you find that after selecting a <code>Subject</code>, you can not select a <code>Chapter</code> (and usually you will see an error from setmaker.js: /webwork2/instructorXMLHandler: e.g. Timeout or Forbidden),<br />
the most common reason is that $server_root_url has not been set "correctly" in the <code>/opt/webwork/webwork2/conf/site.conf</code> file. A common error is to use forget http:// or to use http:// when you should use https:// or to just have the wrong domain name or ip address. But sometimes "localhost" will work when the correct ip address or url will not, for example in situations when you are using a virtual machine as your host (e.g. on AWS).<br />
<br />
If all the above tests work, you can be pretty confident that WeBWorK is working properly.<br />
<br />
Go back to <code>Hmwk Sets Editor</code> on the <code>Main Menu</code>. Then select <code>Import</code>, select <code>setOrientation.def</code> from the <code>from</code> drop down list and select <code>all current users</code> from the <code>assigning this set to</code> drop down list. Then hit <code>Take Action!</code>. Then go through the Orientation problems. This is a good first set to use for introducing students to WeBWorK. Also you can Import <code>set0.def</code> and <code>setMAAtutorial.def</code> and look through those problems.<br />
<br />
If you are new to WeBWorK or even if you are a pro, you should probably add a regular student to myTestCourse and log in as that student to see what the student interface looks like. It's much simpler than the professor or admin interfaces. Also for the same reason you should probably add professor to myTestCourse and log in as that professor to see what the professor interface looks like.<br />
<br />
Click on <code>Classlist Editor</code> on the <code>Main Menu</code>.<br />
Then select <code>Add</code>, for "Add how many students?" pick 2 and hit <code>Take Action!</code>. Then add two students, say <br />
<br />
* <code>Last Name</code> "Smith", <code>First Name</code> "Jane" , <code>Student ID</code> "jsmith" and <code>Login Name</code> "jsmith"<br />
<br />
* <code>Last Name</code> "A", <code>First Name</code> "Prof" , <code>Student ID</code> "profa" and <code>Login Name</code> "profa"<br />
and make sure to select all sets to assign them to both of them. Then hit <code>Add Students</code>.<br />
<br />
Now we make "profa" a professor. Again click on <code>Classlist Editor</code> on the <code>Main Menu</code>. The fast way is to click on the "pencil" by "profa", set the "Permission Level" to "professor" and hit <code>Take Action!</code>.<br />
<br />
Jane Smith's initial password will be her <code>Student ID</code> <code>jsmith</code>. Now login as Jane Smith and play around a little. <br />
<br />
Prof A's initial password will be her <code>Student ID</code> <code>profa</code>. You should also login as Prof A and play around a little. <br />
<br />
You can also add "practice users" and login as one of those to see how you can grant partial access to your course for practice or other reasons (e.g. auditors who don't want to be graded). To do this Click on <code>Classlist Editor</code>, select <code>Import</code>, select the "demoCourse.lst" (the only classlist available at this point) and hit <code>Take Action!</code>.<br />
<br />
==Optional Configurations==<br />
*'''Optional A''' stores WeBWorK's "temporary" files in a separate partition (or directory). <br />
*'''Optional B''' installs and configures a lightweight webserver to serve static files.<br />
*'''Optional C''' configures Apache so that access to WeBWorK will be through SSL.<br />
*'''Optional D''' installs and configures the R server for statistical computing.<br />
*'''Optional E''' sets up log rotation for WeBWorK's timing log.<br />
<br />
===Implement Optional A (wwtmp)===<br />
<br />
Now is the time to implement '''Optional A''' if you choose to do so. Actually you can do this at any time and your active courses will continue to function seemingly without change. The only change behind the scenes will be that temporary files will be stored in a different location. Note that if you want to use this option but did not create <code>wwtmp</code> as a separate partition, you first have to create the directory <code>/var/www/html/wwtmp</code> with the command<br />
sudo mkdir /var/www/html/wwtmp <br />
[sudo] password for wwadmin: <wwadmin password><br />
All of WeBWorK's "temporary" files will be stored under <code>/var/www/html/wwtmp</code>. These are mostly small files such as png images of equations, pdf files, etc. that may be reused but if they are not present (e.g. if they get deleted) they will be seamlessly regenerated on the fly. There is no reason to back up such files and having them in a separate partition or directory means that it is easier and faster to back up other partitions and skip backing up unnecessary files. Even if you do not want to set up a separate partition for this, it is very convenient to at least set up a separate directory for these temporary files and we recommend that yo do so.<br />
<br />
First we set the group and permissions for the <code>wwtmp</code> directory<br />
$ sudo su<br />
[sudo] password for wwadmin: <wwadmin password><br />
# cd /var/www/html<br />
# chown wwadmin wwtmp<br />
# chgrp wwdata wwtmp<br />
# chmod ug+w wwtmp<br />
# chmod g+s wwtmp<br />
# exit<br />
$<br />
Next we have to edit <code>localOverrides.conf</code> so that WeBWorK uses the new <code>wwtmp</code> directory. Since we have a working WeBWorK system, first we make a backup copy of <code>localOverrides.conf</code>.<br />
$ cd /opt/webwork/webwork2/conf<br />
$ cp localOverrides.conf localOverrides.conf.bak1<br />
$ nano localOverrides.conf<br />
Now edit <code>localOverrides.conf</code>. Search for the line<br />
# Directory for temporary files<br />
and under that find the line<br />
# To implement, uncomment the following 6 lines:<br />
Then uncomment (i.e. remove the # symbol) from the 6 lines<br />
#$webworkDirs{htdocs_temp} = '/var/www/html/wwtmp';<br />
#$webworkURLs{htdocs_temp} = '/wwtmp';<br />
#$webworkDirs{equationCache} = "$webworkDirs{htdocs_temp}/equations";<br />
#$webworkURLs{equationCache} = "$webworkURLs{htdocs_temp}/equations";<br />
#$courseDirs{html_temp} = "/var/www/html/wwtmp/$courseName";<br />
#$courseURLs{html_temp} = "/wwtmp/$courseName";<br />
<br />
'''IMPORTANT NOTE'''. Apache 2.4 has changed the default location of the document root from <code>/var/www</code> to <br />
<code>/var/www/html</code> and we are in the process of updating the file <code>localOverrides.conf.dist</code> to reflect this.<br />
If your copy of this file does not have <code>/html</code> in the two lines above, then in addition to uncommenting the 6 lines you also have to add <code>/html</code> in two places.<br />
<br />
Then save the file and quit. If you look at the <code>wwtmp</code> directory you will find it empty but after you restart apache and then access some WeBWorK problems, you will find temporary directories and files in <code>wwtmp</code>. Remember your have to restart apache for these changes to take effect.<br />
<br />
====Using Cron Jobs to remove temporary files====<br />
<br />
It is a good idea to clean out temporary files on a regular automatic schedule. Also pdf copies of downloaded problem sets are saved in a temporary directory (<code>wwtmp/.../hardcopy</code>) so that they can be downloaded from the web. But after the download, the pdf file remains and is visible from the web if one knows the URL. For this reason we recommend deleting all such files that are over one hour old. Similarly we recommend deleting all png, gif, and html links under <code>wwtmp</code> that are over 30 days old. And finally every week we recommend deleting all equation images that are over 14 days old. The following cron jobs will accomplish this. The first is run every 30 minutes, the next three twice a month and the last one weekly on Sunday morning. These cron jobs should be run as root. We use <code>crontab</code> to edit the <code>crontab</code> file:<br />
$ sudo su<br />
[sudo] password for wwadmin: <wwadmin password><br />
# crontab -e<br />
<br />
Now add the following lines at the end of the file<br />
<br />
WEBWORK_ROOT=/opt/webwork/webwork2<br />
*/30 * * * * find /var/www/html/wwtmp/*/hardcopy/* -mmin +60 -name "*" -delete<br />
5 5 1,15 * * find /var/www/html/wwtmp/*/gif/ -mtime +30 -name "*" -delete<br />
5 5 2,16 * * find /var/www/html/wwtmp/*/png/ -mtime +30 -name "*" -delete<br />
5 5 3,17 * * find /var/www/html/wwtmp/*/html/ -mtime +30 -name "*" -delete<br />
4 5 * * 0 /opt/webwork/webwork2/bin/remove_stale_images --delete --days 14<br />
<br />
and save the file and quit<br />
# exit<br />
$<br />
<br />
===Implement Optional B (lighttpd)===<br />
<br />
As is the case for '''Optional A''' you can implement '''Optional B''' at any time and your active courses will continue to function seemingly without change. The only change behind the scenes will be that static images, pages and MathJax (if you installed it locally) will be served by a light weight web server.<br />
====Install and Configure lighttpd====<br />
First we install the light weight webserver <code>lighttpd</code><br />
<br />
Run the command <br />
$ sudo apt install lighttpd<br />
[sudo] password for wwadmin: <wwadmin password><br />
<br />
Now we configure <code>lighttpd</code>. First let's make a backup of the configuration file.<br />
<br />
<br />
$ cd /etc/lighttpd<br />
$ sudo cp lighttpd.conf lighttpd.conf.bak1<br />
[sudo] password for wwadmin: <wwadmin password><br />
<br />
Now edit <code>lighttpd.conf</code>. <br />
<br />
$ sudo nano lighttpd.conf<br />
<br />
<br />
Apache2 is listening on port 80 so we need an alternate port for lighttp to listen to. Standard alternate ports for this are usually 81, 8000, or 8080. 8080 is the only port that is listed as an official alternate at http://en.wikipedia.org/wiki/List_of_TCP_and_UDP_port_numbers . Note that in rare cases an institution may block httpd requests to port 8080. If any of your students report that they can not see graphics, they will have to request that access to requests to port 8080 be allowed.<br />
<br />
Find the line<br />
server.port = 80<br />
and replace it by<br />
server.port = 8080<br />
<br />
Now we make a few more changed that allow MathJax to run under lighttpd. You can skip these if you are running MathJax remotely. At the top of the file in the section <code> server.modules = </code>, under the line<br />
"mod_redirect",<br />
add the line<br />
"mod_setenv",<br />
Then below the closing parentheses and above the line <br />
server.document-root = "/var/www/html"<br />
add the lines<br />
setenv.add-response-header = ( "Access-Control-Allow-Origin" => "*" )<br />
alias.url = ( "/webwork2_files" => "/opt/webwork/webwork2/htdocs/" )<br />
<br />
Then save the file and quit.<br />
<br />
Now restart lighttp<br />
$sudo /etc/init.d/lighttpd restart<br />
<br />
Note that you can just run <code>/etc/init.d/lighttpd</code> to get a list of all options.<br />
<br />
====Test lighttpd====<br />
First run the command<br />
$ sudo lsof -i -P -n | grep LISTEN<br />
and check that lighttpd is listening on port 8080<br />
<br />
Now test your server by connecting to your<br />
server from a browser on a remote machine ("http://yourserver.yourschool.edu:8080/"). You should see the '''Apache2 Ubuntu Default Page''' but without a graphic for the Ubuntu Logo indicating that lighttp is running . Test the <code>/webwork2_files</code> location by visiting "http://yourserver.yourschool.edu:8080/webwork2_files</code>. You should see the "WeBWorK Placeholder Page".<br />
<br />
====Configure WeBWorK to Take Advantage of Lighttp====<br />
<br />
First let's make a backup copy of <code>localOverrides.conf </code> so that we can easily back out of these changes if necessary.<br />
<br />
$ cd /opt/webwork/webwork2/conf<br />
$ cp localOverrides.conf localOverrides.conf.bak2<br />
<br />
<br />
Now edit <code>localOverrides.conf</code>. Note that while '''Optional B''' is independent of '''Optional A''', we assume most people implementing '''Optional B''' will have already implemented '''Optional A'''. Therefore we give instructions for editing <br />
localOverrides.conf assuming that '''Optional A''' has been implemented. If this is not the case, modify the instructions below accordingly. Also replace <code>yourserver.yourschool.edu</code> with the correct address.<br />
<br />
$ nano localOverrides.conf<br />
<br />
Find the line<br />
$webworkURLs{htdocs_temp} = '/wwtmp'<br />
and replace it by<br />
#$webworkURLs{htdocs_temp} = '/wwtmp';<br />
$webworkURLs{htdocs_temp} = 'http://yourserver.yourschool.edu:8080/wwtmp';<br />
<br />
<br />
Find the line<br />
$courseURLs{html_temp} = "/wwtmp/$courseName";<br />
and replace it by<br />
#$courseURLs{html_temp} = "/wwtmp/$courseName";<br />
$courseURLs{html_temp} = "http://yourserver.yourschool.edu:8080/wwtmp/$courseName";<br />
<br />
If you installed MathJax locally under the above line add the lines<br />
# Location of MathJax script, used for the MathJax display mode.<br />
$webworkURLs{MathJax} = 'http://yourserver.yourschool.edu:8080/webwork2_files/mathjax/MathJax.js?config=TeX-MML-AM_HTMLorMML-full';<br />
If you are running MathJax remotely, '''don't add the above lines'''.<br />
<br />
Then save the file and quit.<br />
<br />
Now restart apache and lighttp.<br />
<br />
$ sudo apache2ctl graceful<br />
password:<wwadmin password><br />
$ sudo /etc/init.d/lighttpd restart<br />
<br />
====Test that Everything is Working Properly====<br />
<br />
To test things go to your test course <code>http://yourserver.yourschool.edu/webwork2/myTestCourse/</code>. Log into your course and view a problem with a graphic image (e.g. Problem 2 of the Demo set. Since you have Admin or Prof privileges, you can view sets which are not yet open). Right click on the image and click on Properties (or whatever is appropriate on your browser, e.g. copy image location) and check that the image is being served from port 8080 (something like <code>http://yourserver.yourschool.edu:8080/wwtmp/myTestCourse//gif/...</code>). <br />
<br />
If MathJax is installed locally, to test that MathJax is using lighttpd, view a problem with some typeset equations. Right click on the equation and you should see the MathJax menu which confirms MathJax is being used. Next look at the source code for the page (e.g. right click on most browsers and select "View page source") and in the source, search for mathjax.js. You should see that this is being loaded from port 8080. Obviously, if you are running MathJax remotely, you will see it is being loaded from the CDN.<br />
<br />
====Disabling Optional B (lighttpd) for a single course====<br />
<br />
If your server is hosting courses from different institutions, you may find that you need to disable using lighttpd for a single course, e.g. because the institution blocks access to port 8080. Actually since port 8080 is an "official" alternate httpd port, you should first try to get the network administrators at the institution to grant access to port 8080. Failing this, you can disable using lighttpd and instead use apache for a single course by adding the following lines to the end of the course's <code>course.conf</code> file which is located in the top level directory for the course (usually <code>/opt/webwork/courses/course_name</code>). Note that using apache instead of lighttpd will put a slightly larger load on the server. Also note that you need "admin" level privileges to edit the <code>course.conf</code> file. Instructors with only "professor" level privileges can not do this from within WeBWorK.<br />
If you are running MathJax remotely, don't add the last line.<br />
# Do not use lightppd (port 8080) for this course<br />
$webworkURLs{htdocs_temp} = '/wwtmp';<br />
$courseURLs{html_temp} = "/wwtmp/$courseName";<br />
$webworkURLs{equationCache} = "$webworkURLs{htdocs_temp}/equations";<br />
$webworkURLs{MathJax} = "$webworkURLs{htdocs}/mathjax/MathJax.js?config=TeX-MML-AM_HTMLorMML-full";<br />
'''I repeat if you are running MathJax remotely, don't add the last line above.'''<br />
<br />
===Implement Optional C (SSL)===<br />
'''Optional C''' configures apache so that access to WeBWorK will be through an encrypted connection (SSL) with an https: URL. 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. If you have implemented '''Optional B''', the non encrypted lighttpd server will be used for images, MathJax, etc. so we might have to set up the lighttpd server to run under SSL (see below).<br />
<br />
First we have to obtain an official SSL certificate or generate a self-signed one which can be used for testing purposes. If students will be using your server, it is better to obtain an official SSL certificate since using a self-signed certificate with cause warning messages to be displayed when students connect to the server.<br />
<br />
====Obtain an Official SSL Certificate====<br />
Talk to the networking group on your campus about obtaining an official certificate. You can find information on the net about certificate providers, e.g. http://www.sslshopper.com/certificate-authority-reviews.html .<br />
<br />
The certificate goes in <code>/etc/ssl/certs/</code> and the key file goes in <code>/etc/ssl/private/</code>.<br />
<br />
====Use a self-signed Certificate====<br />
<br />
When we installed the package openssh-server a self-signed certificate was automatically created. The certificate is stored at<br />
/etc/ssl/certs/ssl-cert-snakeoil.pem<br />
and the private key at<br />
/etc/ssl/private/ssl-cert-snakeoil.key<br />
<br />
This certificate and key may be regenerated manually with the following command (needs root privileges ie sudo):<br />
<br />
$ sudo make-ssl-cert generate-default-snakeoil --force-overwrite<br />
[sudo] password for wwadmin: <wwadmin password><br />
<br />
which you might want to do since I believe the original certificate is only valid for 365 days.<br />
<br />
In the instructions below we will use the provided self-signed certificate (ssl-cert-snakeoil.pem and ssl-cert-snakeoil.key) but you can also generate your own using openssh following instructions on the web. As we said above, for a production server, you should really use an official certificate.<br />
<br />
====Set up Apache to use SSL====<br />
<br />
First we enable the <code>mod_ssl</code> module<br />
$ sudo a2enmod ssl<br />
[sudo] password for wwadmin: <wwadmin password><br />
<br />
Now we have to configure Apache to use SSL.<br />
$ cd /etc/apache2/sites-available/<br />
$ sudo cp default-ssl.conf default-ssl.conf.bak1<br />
[sudo] password for wwadmin: <wwadmin password><br />
$ sudo nano default-ssl.conf<br />
<br />
Our self-signed certificate and key files are named <br />
<code>ssl-cert-snakeoil.pem</code> and <code>ssl-cert-snakeoil.key</code>. If you<br />
are using official files, put their names in the lines below. You will also have to edit the Certificate Chain, Certificate Authority and possibly other items. Instructions for doing so are beyond the scope of this document. You might look at https://www.digitalocean.com/community/tutorials/how-to-secure-apache-with-let-s-encrypt-on-ubuntu-18-04<br />
<br />
Search for the lines<br />
SSLCertificateFile /etc/ssl/certs/ssl-cert-snakeoil.pem<br />
SSLCertificateKeyFile /etc/ssl/private/ssl-cert-snakeoil.key<br />
and replace <code>ssl-cert-snakeoil.pem</code> and <code>ssl-cert-snakeoil.key</code> by the names of your certificate. Since in these instructions we are using <br />
<code>ssl-cert-snakeoil.pem</code> and <code>ssl-cert-snakeoil.key</code>, we can just leave the lines as is.<br />
<br />
Then save the file and quit. And enable <code>default-ssl.conf</code> <br />
$ sudo a2ensite default-ssl.conf<br />
[sudo] password for wwadmin: <wwadmin password><br />
Finally we restart Apache<br />
$ sudo systemctl restart apache2<br />
and test things. Connect to https://yourserver.yourschool.edu/webwork2/myTestCourse<br />
You will be asked to accept the certificate. After you do so things should work just as before except that the connection will be via https except for images, MathJax, etc. if you using lighttp. In that case, viewing math expressions in image mode should work fine but it is possible using MathJax mode will fail. We will talk about this below.<br />
<br />
====Redirect http requests to https====<br />
Assuming that everything is working, the last thing we do is set things up so that requests to http://yourserver.yourschool.edu/webwork2/ are automatically redirected to https://yourserver.yourschool.edu/webwork2/.<br />
<br />
$ cd /etc/apache2/sites-available<br />
$ sudo cp 000-default.conf 000-default.conf.bak1<br />
[sudo] password for wwadmin: <wwadmin password><br />
$ sudo nano 000-default.conf<br />
<br />
In the <br />
<VirtualHost *:80><br />
section just under the line<br />
DocumentRoot /var/www/html<br />
add the line<br />
Redirect permanent /webwork2 https://yourserver.yourschool.edu/webwork2<br />
where of course you should edit <code>yourserver.yourschool.edu</code> appropriately.<br />
Then save the file and quit.<br />
Restart Apache<br />
$ sudo service apache2 restart<br />
and try connecting to http://yourserver.yourschool.edu/webwork2/. The real connection should be through https://yourserver.yourschool.edu/webwork2/.<br />
<br />
====Check site.conf====<br />
This is important. We have to check the value of $server_root_url in webwork2/conf/site.conf to make <br />
sure it uses https (so it should read e.g. https://yourserver.yourschool.edu). If<br />
you don't do this, your may run into strange problems in the Library Browser.<br />
To check, open the Library Browser, select a subject and then click on the chapter area. If you see a drop down list of chapters, things are working properly. <br />
<br />
Now we check and edit if necessary site.conf<br />
cd /opt/webwork/webwork2/conf<br />
nano site.conf<br />
<br />
In the line<br />
$server_root_url = ...<br />
replace http by https if necessary. Then save the file, quit and restart apache<br />
sudo service apache2 restart <br />
[sudo] password for wwadmin: <wwadmin password><br />
<br />
===Configure lighttpd to use SSL===<br />
<br />
We are using lighttpd for images, pdf's and MathJax (if MathJax is installed locally) MathJax may fail (so mathematical expressions will not be displayed) if it runs under lighttpd and you do not configure lighttpd to use SSL. So let's configure lighttpd to use SSL.<br />
<br />
For lighttpd you need to concatenate the key file and the certificate file into a single pem file by running the following command.<br />
Obviously you should use the real name of your certificate and key files, not "apache.key" and "apache.crt".<br />
<br />
$ sudo su<br />
[sudo] password for wwadmin: <wwadmin password><br />
# cd /etc/ssl/private<br />
# cat apache.key ../certs/apache.crt > apache.pem<br />
# chmod 640 apache.pem<br />
# exit<br />
$<br />
<br />
If you are using official certificates,<br />
you will also have to edit the Certificate Chain, Certificate Authority and possibly other items. Instructions for doing so are beyond the scope of this document. See e.g.<br />
http://redmine.lighttpd.net/projects/lighttpd/wiki/Docs_SSL and/ or https://www.vultr.com/docs/setup-let-s-encrypt-with-lighttpd-on-ubuntu-16-04 <br />
<br />
<br />
Since we already are using the files <code>ssl-cert-snakeoil.pem</code> and <code>ssl-cert-snakeoil.key</code> for apache, we will also use them for lighttpd<br />
<br />
$ sudo cat /etc/ssl/private/ssl-cert-snakeoil.key /etc/ssl/certs/ssl-cert-snakeoil.pem >/etc/lighttpd/lighttpd.pem<br />
[sudo] password for wwadmin: <wwadmin password><br />
<br />
Now edit <code>lighttpd.conf</code>. <br />
$ cd /etc/lighttpd<br />
$ sudo cp lighttpd.conf lighttpd.conf.bak2<br />
[sudo] password for wwadmin: <wwadmin password><br />
$ sudo nano lighttpd.conf<br />
<br />
First in the list of <code>server.modules</code> at the top of the file, under the last module <code>"mod_setenv",</code>, add the module<br />
"mod_openssl",<br />
<br />
Next under the line<br />
server.port = 8080<br />
add the following<br />
$SERVER["socket"] == ":8443" {<br />
ssl.engine = "enable"<br />
ssl.pemfile = "/etc/lighttpd/lighttpd.pem"<br />
}<br />
<br />
Then save the file and quit.<br />
<br />
And restart lighttpd and check it's status<br />
<br />
$ sudo systemctl restart lighttpd<br />
[sudo] password for wwadmin: <wwadmin password><br />
$ sudo systemctl status lighttpd<br />
<br />
Sometimes when Lighttpd would not restart (or start) I just rebooted the server and everything worked. If you have difficulty you can run the command<br />
$ sudo lsof -i -P -n | grep LISTEN<br />
which will list all the ports your server is listening to. In the list you should see something similar to<br />
lighttpd 519 www-data 5u IPv4 18610 0t0 TCP *:8443 (LISTEN)<br />
<br />
<br />
====Edit localOverrides.conf</code>====<br />
$ cd /opt/webwork/webwork2/conf<br />
$ cp localOverrides.conf localOverrides.conf.bak4<br />
$ nano localOverrides.conf<br />
and replace all occurrences of 8080 by 8443 (one occurrence in three different lines). Then in these same three lines replace <code>http</code> by <code>https</code> . Obviously, you have to edit the three active lines and can ignore the commented out lines.<br />
<br />
Then save the file and quit. And restart apache<br />
$ sudo service apache2 restart<br />
[sudo] password for wwadmin: <wwadmin password><br />
<br />
and test that all is well by viewing a page with math expressions using MathJax mode.<br />
<br />
===Implement Optional D (Rserve)===<br />
<br />
Here we will install and configure the R server for statistical computing. Many statistics and probability problems (mostly contributed by faculty at the University of British Columbia) require this.<br />
<br />
See the documentation (from which we have borrowed heavily) [[R_in_WeBWorK]] for more detailed information.<br />
<br />
====Install the R server====<br />
$ sudo apt install r-cran-rserve<br />
[sudo] password for wwadmin: <wwadmin password><br />
<br />
and check that R is running<br />
$ R<br />
<br />
You should see something very similar to <br />
<br />
R version 3.6.3 (2020-02-29) -- "Holding the Windsock"<br />
Copyright (C) 2020 The R Foundation for Statistical Computing<br />
...<br />
Type 'q()' to quit R.<br />
<br />
><br />
and then quit<br />
> q()<br />
Save workspace image? [y/n/c]: n<br />
<br />
====Configure Webwork with the location of the R server====<br />
Edit the localOverrides.conf file<br />
<br />
$ cd /opt/webwork/webwork2/conf<br />
$ nano localOverrides.conf<br />
<br />
Search for the line<br />
$pg{specialPGEnvironmentVars}{DragMath}<br />
and under that line add the following<br />
<br />
################################################################################<br />
#location of the R server<br />
################################################################################<br />
$pg{specialPGEnvironmentVars}{Rserve} = {host => 'localhost'};<br />
<br />
Then save the file and Quit.<br />
<br />
====Set up Rserve to run as a daemon at system boot====<br />
<br />
This is somewhat complicated. I'm basically following instructions from https://github.com/geordielad/rserve-systemd-unit<br />
<br />
First we create a user with limited privileges to run rserve.<br />
<br />
$ sudo adduser rserveuser --system --shell=/bin/false --no-create-home --disabled-password --disabled-login<br />
<br />
<br />
Next we create a file to automatically start Rserve<br />
<br />
$ cd<br />
$ nano rserve.service<br />
Now copy and paste the following code into nano<br />
<br />
[Unit]<br />
Description=Rserve<br />
<br />
[Service]<br />
Type=forking<br />
PIDFile=/var/run/rserve/rserve.pid<br />
<br />
# Define runtime directory<br />
RuntimeDirectory=rserve<br />
RuntimeDirectoryMode=750<br />
<br />
User=rserveuser<br />
Group=nogroup<br />
<br />
ExecStart=/usr/bin/R CMD Rserve --quiet --vanilla --RS-pidfile /var/run/rserve/rserve.pid<br />
<br />
[Install]<br />
WantedBy=multi-user.target<br />
<br />
and then save the file and quit.<br />
Change the owner to root, move the file to the proper location and register it.<br />
<br />
$ sudo chown root:root rserve.service<br />
[sudo] password for wwadmin: <wwadmin password><br />
$ sudo mv rserve.service /etc/systemd/system<br />
$ sudo systemctl daemon-reload<br />
<br />
Finally we enable the service to start when the system starts<br />
<br />
$ sudo systemctl enable rserve.service<br />
<br />
====Test that things are working properly====<br />
<br />
First start Rserve manually<br />
$ sudo systemctl start rserve<br />
[sudo] password for wwadmin: <wwadmin password><br />
and run <br />
$ sudo lsof -i -P -n | grep LISTEN<br />
and you should see that Rserve is listening on port 6311<br />
<br />
Next test that WeBWorK problems using R run properly. In WeBWorK, click on <code>Library Browser</code> on the <code>Main Menu</code>. Then click <code>Open Problem Library </code> (actually it should already be selected so it will be greyed out). <br />
Now 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 />
<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 />
Finally reboot your server (to test that the Rserve starts automatically on boot up) and run <br />
$ sudo systemctl status rserve.service<br />
[sudo] password for wwadmin: <wwadmin password><br />
to check that all is well and just to be redundant <br />
$ sudo lsof -i -P -n | grep LISTEN<br />
again. Now we are sure that Rserve automatically starts when the system is booted.<br />
<br />
====Loading additional modules====<br />
This step should not be necessary unless you are writing or using WeBWorK problems that need additional resources beyond what is loaded by default. An example is using R to compute complex eigenvalues which requires the <code>Math::Complex</code> module (see https://webwork.maa.org/moodle/mod/forum/discuss.php?d=5577). The error message in such a case would be similar to <br />
Can't locate object method "make" via package "Math::Complex" (perhaps you forgot to load "Math::Complex"?) at /usr/share/perl/5.30/Math/Complex.pm line 329<br />
Died within Math::Complex::cplx called at line 351 of /usr/local/share/perl/5.30.0/Statistics/R/IO/QapEncoding.pm<br />
from within Statistics::R::IO::QapEncoding::decode called at line 236 of /usr/local/share/perl/5.30.0/Statistics/R/IO/Rserve.pm<br />
from within Statistics::R::IO::Rserve::eval called at line 26 of [PG]/lib/Rserve.pm<br />
from within Rserve::try_eval called at line 146 of [PG]/macros/RserveClient.pl<br />
from within main::rserve_eval called at line 40 of (eval 4456)<br />
<br />
First note that the required module must be installed on your server (see [[#Installing Perl Modules|Installing Perl Modules]] above). The <code>Math::Complex</code> module already is.<br />
<br />
We need to load <code>Math::Complex</code> into WeBWorK's safe compartment. For this we have to edit the localOverrides.conf file.<br />
<br />
$ cd /opt/webwork/webwork2/conf<br />
$ nano localOverrides.conf<br />
Now search for the line<br />
# Additional PG modules<br />
and under the line<br />
#push (@{${pg}{modules}}, [qw(TikZ_Image2)]);<br />
add the lines<br />
push @{$pg{modules}},<br />
[qw( Math::Complex )],<br />
; <br />
You can add as many modules as you need this way.<br />
<br />
Then save the file and Quit.<br />
<br />
===Implement Optional E (Logrotate)===<br />
Here we will set up log rotation for WeBWorK's timing log which can grow huge especially if you have a large number of users. The <code>timing.log</code> gives timing information on every action in WeBWorK (see [[WeBWorK_performance]]) and can be used to assess the performance of your server.<br />
<br />
====Create a WeBWorK configuration file for Logrotate====<br />
Logrotate’s configuration files are located in <code>/etc/logrotate.d</code>. Now we create one for WeBWorK.<br />
<br />
$ sudo nano /etc/logrotate.d/webwork<br />
<br />
Now copy and paste the following code into nano<br />
/opt/webwork/webwork2/logs/timing.log {<br />
su www-data wwdata<br />
weekly<br />
missingok<br />
rotate 15<br />
compress<br />
delaycompress<br />
notifempty<br />
}<br />
and then save the file and quit. The backup will be done weekly and we are keeping 15 weeks (approximately one semester) worth of logs. <br />
The most recent backup will not be compressed but all older ones will be. We are not explicitly creating a new <code>timing.log</code> file <br />
because WeBWorK will automatically create one if it's missing. If you want to check that it works you can run <code>logrotate</code><br />
with the configuration file (make sure you have done something with WeBWorK so that the <code>timing.log</code> is not empty):<br />
<br />
sudo logrotate -f /etc/logrotate.d/webwork<br />
[sudo] password for wwadmin: <wwadmin password><br />
<br />
Then if you look in <code>/opt/webwork/webwork2/logs</code>, you should see<br />
<br />
timing.log.1<br />
<br />
You will not see a <code>timing.log</code> file unless someone has been doing something with WeBWorK. If there is no <code>timing.log</code> file<br />
do something yourself (e.g. login to a course) and then you should see <br />
<br />
timing.log<br />
timing.log.1<br />
<br />
Now run <code>logrotate</code> again <br />
sudo logrotate -f /etc/logrotate.d/webwork<br />
[sudo] password for wwadmin: <wwadmin password><br />
and do something in WeBWorK and you should see<br />
<br />
timing.log<br />
timing.log.1<br />
timing.log.2.gz<br />
<br />
Here is what is going on. <code>timing.log.1</code> was renamed to <code>timing.log.2</code> and compressed giving <code>timing.log.2.gz</code>. <code>timing.log</code> was renamed to <code>timing.log.1</code>. <br />
And the something you (or someone else) did in WeBWorK created a new <code>timing.log</code> file. A similar procedure will happen weekly until there are a total of <br />
15 backups after which the oldest one will be deleted.<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. <br />
<br />
To fix this 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", "HTML_tth", ],<br />
<br />
Then save the file and Quit.<br />
<br />
This may or may not be addressed in a WeBWorK 15 hotfix (see [[#Checking for and Installing Hotfixes|Checking for and Installing Hotfixes]]).<br />
<br />
===UTF-8 support===<br />
WW 2.15 has some "known issues" with the UTF-8 support that arise in some WeBWorK problems. These issues are discussed in a forum discussion at: <br />
https://webwork.maa.org/moodle/mod/forum/discuss.php?d=4795. The discussion there lists pull requests by <br />
Nathan Wallach and Davide Cervone that address these issues. If you write or use WeBWorK problems that have issues with UTF-8 characters,<br />
look at that discussion. Again these issues may or may not be addressed in a WeBWorK 15 hotfix (see [[#Checking for and Installing Hotfixes|Checking for and Installing Hotfixes]]).<br />
<br />
Systems using UTF-8 problems probably need to patch /usr/share/perl5/XMLRPC/Lite.pm as explained at https://github.com/openwebwork/webwork2/issues/967#issuecomment-523941959 and may want to consider the fixes accepted in the develop branch via https://github.com/openwebwork/webwork2/pull/1089 and https://github.com/openwebwork/pg/pull/466 .<br />
<br />
==Where to go From Here ==<br />
<br />
You should play around with <code>myTestCourse</code> e.g. click on <code>Library Browser</code> and browse the <code>Problem Library</code>.<br />
<br />
Look at [[A day in the life of a WeBWorK instructor]].<br />
<br />
Read [[Course Administration]] for more information about creating courses.<br />
<br />
Under Categories below click on Administrators to see a listing of other WeBWorK documentation for system administrators.<br />
<br />
-- Main.ArnoldPizer update by Peter Staab - 19 May 2021 <br /><br />
<br />
[[Category:Administrators]]<br />
[[Category:Installation Manuals]]</div>141.154.51.251https://webwork.maa.org/mediawiki_new/index.php?title=Installation_Manual_for_2.16_on_Ubuntu&diff=20908Installation Manual for 2.16 on Ubuntu2021-05-19T20:45:32Z<p>141.154.51.251: /* Installing a Database */</p>
<hr />
<div><br />
{{UnderConstruction}}<br />
<br />
'''These instructions are a work in progress. '''<br />
<br />
<br />
These instructions cover the installation of WeBWorK 2.16 for Ubuntu Server 20.04 LTS, XXX and XXX. Specific OS instruction are embedded within this document<br />
<br />
If you are just upgrading WeBWorK, especially if you already have existing WeBWorK courses, see [[Upgrading_WeBWorK_with_Github]].<br />
<br />
Also, it is assumed that you have an operating system installed. You can visit [[Category:Installation_Manuals]] for instructions on installing the operating system or google how to install your favorite linux flavor. Also make sure the OS is upgraded to all patches within the version you are running. <br />
<br />
== Notation ==<br />
<br />
First some short comments on notation we will be using. We will use <code>&lt;key&gt;</code> to indicate that you should press a specific key (e.g. <code>&lt;Enter&gt;</code>, <code>&lt;Tab&gt;</code>, <code>&lt;F12&gt;</code>, etc.). Sometimes we will also use e.g. <code>&lt;wwadmin password&gt;</code> to indicate you have to enter the wwadmin password.<br />
<br />
<code>^</code> will indicate the <code>&lt;Ctrl&gt;</code> key so e.g. <code>^X</code> is really shorthand for <code>&lt;Ctrl&gt; &lt;X&gt;</code>, i.e. press the Ctrl key and hit the X key.<br />
<br />
==Install Software Packages==<br />
<br />
=== Ubuntu Software Packages ===<br />
<br />
On Ubuntu and other Debian linuxes, the following instructions will get needed software packages installed. <br />
<br />
Here is the list of Ubuntu packages that need to be installed. <br />
<br />
# <code>apache2</code><br />
# <code>cpanminus</code><br />
# <code>curl</code><br />
# <code>dvipng</code><br />
# <code>gcc</code><br />
# <code>git</code><br />
# <code>imagemagick</code><br />
# <code>libapache2-request-perl</code><br />
# <code>libarchive-zip-perl</code><br />
# <code>libarray-utils-perl</code><br />
# <code>libcrypt-ssleay-perl</code><br />
# <code>libdatetime-perl</code><br />
# <code>libdata-dump-perl</code><br />
# <code>libemail-address-xs-perl</code><br />
# <code>libemail-sender-perl</code><br />
# <code>libexception-class-perl</code><br />
# <code>libextutils-xsbuilder-perl</code><br />
# <code>libfile-find-rule-perl-perl</code><br />
# <code>libgd-perl</code><br />
# <code>libhtml-scrubber-perl</code><br />
# <code>libhttp-async-perl</code><br />
# <code>libiterator-perl</code><br />
# <code>libiterator-util-perl</code><br />
# <code>libjson-perl</code><br />
# <code>liblocale-maketext-lexicon-perl</code><br />
# <code>libmime-tools-perl</code><br />
# <code>libmoox-options-perl</code><br />
# <code>libnet-ip-perl</code><br />
# <code>libnet-ldap-perl</code><br />
# <code>libnet-oauth-perl</code><br />
# <code>libossp-uuid-perl</code><br />
# <code>libpadwalker-perl</code><br />
# <code>libpath-class-perl</code><br />
# <code>libphp-serialization-perl</code><br />
# <code>libpod-wsdl-perl</code><br />
# <code>libsoap-lite-perl</code><br />
# <code>libsql-abstract-perl</code><br />
# <code>libstring-shellquote-perl</code><br />
# <code>libtemplate-perl</code><br />
# <code>libtext-csv-perl</code><br />
# <code>libtimedate-perl</code><br />
# <code>libuuid-tiny-perl</code><br />
# <code>libxml-parser-easytree-perl</code><br />
# <code>libxml-parser-perl</code><br />
# <code>libxml-writer-perl</code><br />
# <code>make</code><br />
# <code>netpbm</code><br />
# <code>npm</code><br />
# <code>pdf2svg</code><br />
# <code>preview-latex-style</code><br />
# <code>texlive</code><br />
# <code>texlive-latex-extra</code><br />
# <code>unzip</code><br />
<br />
<br />
'''To install all of these packages in one fell swoop''', first become root: <br />
$ sudo su<br />
[sudo] password for wwadmin: <wwadmin password><br />
<br />
and then run the command ('''obviously you want to use cut and paste''')<br />
# apt install apache2 cpanminus curl dvipng gcc git imagemagick libapache2-request-perl \<br />
libarchive-zip-perl libarray-utils-perl libcrypt-ssleay-perl libdancer-perl libdancer-plugin-database-perl \<br />
libdata-dump-perl libdatetime-perl libemail-address-xs-perl libemail-sender-perl \<br />
libexception-class-perl libextutils-xsbuilder-perl libfile-find-rule-perl-perl \<br />
libgd-perl libhttp-async-perl libhtml-scrubber-perl libiterator-perl libiterator-util-perl libjson-perl \<br />
liblocale-maketext-lexicon-perl libmime-tools-perl libmoox-options-perl libnet-ip-perl libnet-ldap-perl \<br />
libnet-oauth-perl libossp-uuid-perl libpadwalker-perl libpath-class-perl \<br />
libphp-serialization-perl libpod-wsdl-perl \<br />
libsoap-lite-perl libsql-abstract-perl libstring-shellquote-perl libtemplate-perl \<br />
libtext-csv-perl libtimedate-perl libuuid-tiny-perl libxml-parser-easytree-perl \<br />
libxml-parser-perl libxml-writer-perl make netpbm npm pdf2svg \<br />
preview-latex-style texlive texlive-latex-extra unzip<br />
<br />
If prompted, you can always accept the default (hit <code>&lt;Enter&gt;</code>). When the process finishes, enter<br />
# exit<br />
to return to a regular user.<br />
<br />
=== Installation of Other Perl Modules with cpanm ===<br />
<br />
We will use <code>cpanm</code> to install other perl modules. For example, one module, <code>Statistics::R::IO</code> that will be needed is not in a standard package. To install this<br />
<pre><br />
cpanm Statistics::R::IO<br />
</pre><br />
<br />
Below, we will determine other perl modules that will need to be installed with this method. <br />
<br />
== Apache2 Modules and mod perl ==<br />
<br />
The following loads needed apache modules.<br />
<br />
=== enabling info.conf and status.conf in Ubuntu ===<br />
<br />
We enable the info module. Acting as <code>root</code> in a terminal window enter<br />
$ sudo su<br />
[sudo] password for wwadmin: <wwadmin password><br />
# a2enmod info<br />
<br />
Next we make a copy of the configuration files we will be editing for safekeeping. <br />
<br />
# cd /etc/apache2/mods-available<br />
<br />
# cp info.conf info.conf.bak1<br />
# cp status.conf status.conf.bak1<br />
<br />
# exit<br />
$<br />
<br />
Now we will edit configuration files <code>info.conf</code> and <code>status.conf</code> to allow us to view information about the setup and performance of the web server. Note that this is not absolutely necessary but it can be very useful. You can use your favorite editor but we will give instructions assuming you are using <code>nano</code>. Note that you have to be root to edit these files. First we edit <code>info.conf</code><br />
<br />
$ cd /etc/apache2/mods-available<br />
$ sudo nano info.conf<br />
[sudo] password for wwadmin: <wwadmin password><br />
<br />
I suggest you allow access to server information from e.g. your department domain. To do this uncomment (i.e. remove the <code>#</code> from) <br />
Require ip 192.0.2.0/24<br />
and then replace <code>192.0.2.0/24</code> by <code>.math.yourschool.edu</code><br />
where of course you should edit <code>.math.yourschool.edu</code> appropriately. <br />
<br />
Then save the file and quit (press <code>^X</code>, <code>Y</code>, <code>&lt;Enter&gt;</code>).<br />
<br />
Now we edit <code>status.conf</code><br />
<br />
$ cd /etc/apache2/mods-available<br />
$ sudo nano status.conf<br />
[sudo] password for wwadmin: <wwadmin password><br />
<br />
Edit the <br />
#Require ip 192.0.2.0/24<br />
line just as you did for <code>info.conf</code>.<br />
Then save the file and quit. And restart Apache so that the above changes take effect<br />
<br />
$ sudo systemctl restart apache2<br />
password:<wwadmin password><br />
<br />
===Fully Qualified Domain Name=== <br />
Now we have to set your server's fully qualified domain name. Note that if your network was set up automatically via DHCP, your server's fully qualified domain name should already be set up. You can check by running the <code>hostname</code> commands below.<br />
<br />
Run the command <br />
sudo hostnamectl set-hostname webwork<br />
[sudo] password for wwadmin: <wwadmin password><br />
where of course you should replace webwork by whatever your server's name is.<br />
<br />
<br />
You can check these settings by running the commands<br />
<br />
$ hostname --fqdn<br />
and <br />
$ hostname<br />
<br />
The first gives the server's fully qualified domain name (e.g. webwork.mydepartment.myschool.edu) and the second the server's name (e.g. webwork).<br />
<br />
Note that if your server can not find its fully qualified domain name, certain tools (such as the Synaptic Package Manager) may not start.<br />
<br />
===Test Apache===<br />
Now restart Apache<br />
<br />
$ sudo systemctl restart apache2<br />
password:<wwadmin password><br />
or<br />
$ sudo apache2ctl restart<br />
[sudo] password for wwadmin: <wwadmin password><br />
or<br />
$ sudo service apache2 restart<br />
[sudo] password for wwadmin: <wwadmin password><br />
<br />
<br />
and test your server by connecting to your<br />
server ("http://yourserver.yourschool.edu") from a browser on a remote machine. You should see the '''Apache2 Ubuntu Default Page''' indicating that Apache is running.<br />
<br />
You can check Apache's status by connecting to<br />
"http://yourserver.yourschool.edu/server-status" from a browser on a remote machine in the math.yourschool.edu domain.<br />
<br />
Further test Apache by connecting to<br />
"http://yourserver.yourschool.edu/server-info" from a browser on a remote machine in the math.yourschool.edu domain and you will see a page listing various <br />
information about Apache. In particular under <code>Server Settings</code> you should see<br />
<br />
Server Version: Apache/2.4.41 (Ubuntu) mod_apreq2-20090110/2.8.0 mod_perl/2.0.11 Perl/v5.30.0<br />
(or something very similar) indicating that both <code>mod_apreq2</code> and <code>mod_perl</code> are installed.<br />
<br />
If you have problems now or in the future, a good first thing to do is to look at the Apache error log which is located at <code>/var/log/apache2/error.log</code>. In the directory <code>/var/log/apache2/</code> you can "less" through the error log (<code>less error.log</code>), look at the last few entries (<code>tail error.log</code>) or run the command <code>tail -f error.log</code> which will display new error messages as they are appended to the file. Use <br />
<code>^C</code> to break out of <code>tail -f</code> . For example if you didn't set up access to "server-info", you can run<br />
tail /var/log/apache2/error.log<br />
and in the output you should see something similar to<br />
...[mpm_event:notice] [pid 48932:tid 140494759132224] AH00489: Apache/2.4.41 (Ubuntu) mod_apreq2-20090110/2.8.0 mod_perl/2.0.11 Perl/v5.30.0 configured -- resuming normal operations<br />
indicating that both <code>mod_apreq2</code> and <code>mod_perl</code> are installed and running.<br />
<br />
== Installing a Database ==<br />
<br />
This section installs either MySQL or MariaDB as the database manger for webwork. It is recommended that MariaDB is used. There have been a few examples of connection issues with MySQL. <br />
<br />
<br />
=== Installing and Testing MariaDB ===<br />
<br />
Install MariaDB using the distro packages. <br />
<br />
$ sudo apt install mariadb-server libdbd-mariadb-perl<br />
<br />
<br />
=== Installing and Testing MySQL ===<br />
<br />
If you wish to use MySQL: <br />
<br />
$ sudo apt install mysql-server libdbd-mysql-perl<br />
<br />
=== Securing the DataBase ===<br />
<br />
Then we should secure the server<br />
<br />
$ sudo mysql_secure_installation<br />
[sudo] password for wwadmin: <wwadmin password><br />
<br />
You can setup the VALIDATE PASSWORD plugin if you wish. I chose not to.<br />
<br />
Next you will be asked to enter a<br />
<code>New password for the MySQL "root" user</code>. Enter your chosen MySQL <code>root</code> password. You have to enter a password but it will not be used. In Ubuntu systems running MySQL 5.7 (and later versions), the root MySQL user is set to authenticate using the auth_socket plugin by default rather than with a password. <br />
<br />
You almost certainly want to answer 'Y' to all questions '''except''' possibly for the first one which asks if you want to set up a VALIDATE PASSWORD plugin.<br />
Now test that all is well:<br />
<br />
$ sudo mysql <br />
[sudo] password for wwadmin: <wwadmin password><br />
<br />
You should see<br />
<br />
Welcome to the MySQL monitor ...<br />
mysql><br />
<br />
Now lets check the MySQL users.<br />
There are five accounts. To see the accounts, do the following <br />
<br />
mysql> SELECT user,authentication_string,plugin,host FROM mysql.user;<br />
<br />
You will see a table with five users (<code>debian-sys-maint</code>, <code>mysql.infoschema</code>, <code>mysql.session</code>, <code>mysql.sys</code> and <code>root</code>). <br />
You should see that one of the five users has a valid password (which will be displayed in encrypted form) and <code>root</code> is authenticated by a socket. You can ignore the <code>mysql.session</code>, <code>mysql.sys</code> and <code>mysql.infoschema</code> users.<br />
<br />
Now exit MySQL<br />
<br />
mysql> exit<br />
Bye<br />
$<br />
<br />
This last step is optional since currently most of WeBWorK's MySQL tables are now created using the MyISAM engine (by default -- this can be changed in the config files) rather than the MySQL default engine. Now we change MySQL's default engine. The default engine is InnoDB as of MySQL 5.5.5 (MyISAM before 5.5.5) but (at least on some hardware) InnoDB seems to be 50-100 times slower than MyISAM. So we will change the default MySQL engine from InnoDB to MyISAM. Note that this change only applies to new tables, tables already constructed will continue to use InnoDB. But we haven't created any WeBWorK tables so we don't have to change the engine for any existing tables. <br />
<br />
=== Changing the default MySQL/MariaDB engine ===<br />
<br />
To change the default MySQL engine from InnoDB to MyISAM do the following:<br />
<br />
$ cd /etc/mysql/mysql.conf.d<br />
$ sudo cp mysqld.cnf mysqld.cnf.bak1<br />
[sudo] password for wwadmin: <wwadmin password><br />
$ sudo nano mysqld.cnf<br />
<br />
Search for <code>[mysqld]</code> and under "Basic Settings" above the "user = mysql" line add the line<br />
default-storage-engine = myisam <br />
<br />
Then save the file and quit. Restart Mysql<br />
<br />
$ sudo /etc/init.d/mysql restart<br />
[sudo] password for wwadmin: <wwadmin password><br />
or<br />
$ sudo service mysql restart<br />
[sudo] password for wwadmin: <wwadmin password><br />
<br />
and log into mysql<br />
$ sudo mysql <br />
[sudo] password for wwadmin: <wwadmin password><br />
<br />
You will see<br />
<br />
Welcome to the MySQL monitor ...<br />
mysql><br />
<br />
If you show MySQL engines<br />
<br />
mysql> SHOW ENGINES\G<br />
<br />
you should see that MyISAM is listed as the default engine:<br />
...<br />
*************************** 5. row ***************************<br />
Engine: MyISAM<br />
Support: DEFAULT<br />
Comment: MyISAM storage engine <br />
Transactions: NO<br />
XA: NO<br />
Savepoints: NO<br />
<br />
Now exit<br />
mysql> exit<br />
Bye<br />
$<br />
<br />
== Downloading the WeBWorK System Software and Problem Libraries ==<br />
We are finally at the point where we can start downloading and installing WeBWorK. We will use Git to download WeBWorK from Github. This is easy and it will also make it easy to update the system in the future. Note that the following are rather long commands; it is much easier to copy (<code>^C</code>) them from this document and paste (<code>&lt;Shift&gt; &lt;Ctrl&gt; &lt;V&gt;</code><br />
or <code>&lt;Shift&gt; &lt;Insert&gt;</code>) them in a terminal window<br />
<br />
$ cd<br />
$ cd downloads<br />
$ git clone git://github.com/openwebwork/webwork2.git<br />
$ git clone git://github.com/openwebwork/pg.git<br />
$ git clone git://github.com/openwebwork/webwork-open-problem-library.git<br />
<br />
'''Important Note'''. The above commands retrieve the master branch which gives the latest stable release of the software package (webwork2, pg, etc.) with bug fixes. If a stable release newer than 2.15 exists, that will be downloaded and these instructions may be a little out of date. So it is a good idea to check before downloading. The best way to do that is to look at https://github.com/openwebwork/webwork2/blob/master/VERSION and https://github.com/openwebwork/pg/blob/master/VERSION.<br />
<br />
The first and second download gives you the latest released versions.<br />
The third download contains the WeBWorK Open Problem Library (OPL) which is the new name for the original National Problem Library (NPL). The NPL has been renamed to reflect its growing international content. Your system will be loaded with many thousands of WeBWorK problems (over 30,000 currently).<br />
<br />
The main information page about WebWork downloads is available at http://webwork.maa.org/wiki/Category:Release_Notes<br />
<br />
The main information page about the OPL is available at http://webwork.maa.org/wiki/Open_Problem_Library<br />
<br />
==Installing WeBWorK==<br />
<br />
'''Note the instructions below assume you are installing WeBWorK from scratch. If you are just upgrading WeBWorK, especially if you already have existing WeBWorK courses, see [[Upgrading WeBWorK]].'''<br />
<br />
=== Move the System into the Required Directories ===<br />
As <code>root</code> create a <code>webwork</code> directory under <code>/opt</code>, change the ownership of the <code>webwork</code> directory to <code>www-data</code>, which is what the apache server runs as and move directories there. <br />
<br />
$ cd<br />
$ cd downloads<br />
$ sudo mkdir /opt/webwork<br />
[sudo] password for wwadmin: <wwadmin password><br />
$ sudo chown www-data:www-data /opt/webwork<br />
$ mv webwork2 /opt/webwork/<br />
$ mv pg /opt/webwork/<br />
<br />
<br />
<br />
Now create the <code>courses</code> and <code>libraries</code> directories under <code>webwork</code> and copy and move content there <br />
<br />
$ mkdir /opt/webwork/courses<br />
$ mkdir /opt/webwork/libraries<br />
$ mv webwork-open-problem-library /opt/webwork/libraries/<br />
$ cd /opt/webwork/webwork2/courses.dist<br />
$ cp *.lst /opt/webwork/courses/<br />
$ rsync -a modelCourse /opt/webwork/courses/<br />
<br />
=== Setting Permissions ===<br />
<br />
The PG installation directory and files should be owned by <code>www-data</code> and not writable by other users:<br />
<br />
$ cd /opt/webwork/pg<br />
$ chmod -R u+rwX,go+rX .<br />
<br />
Most WeBWorK directories and files should also be owned by <code>www-data</code> and not writable by other users:<br />
<br />
$ cd /opt/webwork/webwork2<br />
$ chmod -R u+rwX,go+rX .<br />
<br />
Certain data directories need to be writable by the web server. These are <code>DATA</code>, <code>courses</code>, <code>htdocs/tmp</code>, <code>logs</code>, and <code>tmp</code>. It is convenient to give WeBWorK administrators access to these directories as well, so they can perform administrative tasks such as removing temporary files, creating and editing courses from the command line, managing logs, and so on. We will use the group <code>www-data</code>, containing both the WeBWorK administrators and the web server. Consider the user WWADMIN<br />
<br />
Run the command:<br />
$ sudo adduser WWADMIN www-data<br />
<br />
$ id WWADMIN<br />
<br />
and then you should see <code>wwdata</code> listed under groups. Also<br />
<br />
$ id www-data<br />
<br />
should show <code>www-data</code> listed under groups. <br />
<br />
Now we make the WeBWorK directories that need to be writable by the web server have <code>www-data</code> as their group. The following are rather long commands; you might want to copy them and paste them into your terminal window rather than typing them.<br />
<br />
$ sudo su<br />
[sudo] password for wwadmin: <wwadmin password><br />
# cd /opt/webwork/webwork2/<br />
# chgrp -R www-data DATA ../courses htdocs/tmp htdocs/applets logs tmp /opt/webwork/pg/lib/chromatic<br />
# chmod -R g+w DATA ../courses htdocs/tmp htdocs/applets logs tmp /opt/webwork/pg/lib/chromatic<br />
# find DATA/ ../courses/ htdocs/tmp logs/ tmp/ -type d -a -exec chmod g+s {} \;<br />
# exit<br />
$<br />
<br />
=== Compile color.c ===<br />
<br />
$ cd /opt/webwork/pg/lib/chromatic<br />
$ gcc color.c -o color<br />
<br />
You may see some warning messages which you can safely ignore.<br />
<br />
== Configuring the Shell ==<br />
<br />
To make working with WeBWorK easier, there are a couple of changes you can make to your shell environment.<br />
<br />
Add the WeBWorK <code>bin</code> directory to your path. This will allow you to run WeBWorK command-line utilities without typing the full path to the utility. Goto your home directory and backup your <code>.bashrc</code> file<br />
<br />
$ cd<br />
$ cp .bashrc .bashrc.bak1<br />
<br />
Now edit <code>.bashrc</code><br />
<br />
$ nano .bashrc<br />
<br />
After the last line add the three lines:<br />
<br />
export PATH=$PATH:/opt/webwork/webwork2/bin<br />
export WEBWORK_ROOT=/opt/webwork/webwork2<br />
export PG_ROOT=/opt/webwork/pg<br />
<br />
Then save the file and Quit.<br />
<br />
Close your Terminal Window and open a new one so the above changes<br />
take effect. You can check that they have by<br />
<br />
$ echo $PATH<br />
$ echo $WEBWORK_ROOT<br />
$ echo $PG_ROOT<br />
<br />
== Checking Module Dependencies ==<br />
<br />
WeBWorK includes a script called <code>check_modules.pl</code> (in the directory <code>/opt/webwork/webwork2/bin</code>) that verifies that the needed programs and Perl modules are installed on your system. Run this script to make sure you have installed the required programs and Perl modules.<br />
<br />
$ check_modules.pl apache2<br />
<br />
Scroll up and look through the listing. It should find everything. If something is missing (flagged by <code>**</code>), look back through these instructions to find where it should have been installed and install it. <br />
<br />
You may see some warning messages like <br />
Prototype mismatch: sub main::from_json: none vs ($@) at (eval 188) line 2.<br />
Prototype mismatch: sub main::to_json: none vs ($@) at (eval 188) line 2.<br />
This is a known bug in libjson-perl and can be safely ignored.<br />
<br />
A common perl package that isn't installed is <code>Statistics::R::IO</code>. It can be installed with<br />
<br />
$ cpanm Statistics::R::IO<br />
<br />
which will install any needed dependencies and run tests. <br />
<br />
=== Obtaining Javascript Libraries ===<br />
<br />
Javascript libraries are now obtained using <code>npm</code>. This includes the following javascript packages:<br />
<br />
# <code>codemirror</code><br />
# <code>fontawesome</code><br />
# <code>iframe-resizer</code><br />
# <code>jQuery</code><br />
# <code>jQuery-ui</code><br />
# <code>MathJax</code><br />
# <code>nestedSortable</code><br />
<br />
To install all of these: <br />
<br />
$ cd /opt/webwork/webwork2/htdocs/<br />
$ npm install<br />
<br />
=== Checking LaTeX packages ===<br />
<br />
Now we check that all necessary LaTeX packages have been installed. Run the commands<br />
$ cd<br />
$ pdflatex /opt/webwork/webwork2/bin/check_latex.tex<br />
and look for missing packages (you can ignore "No file check_latex.aux.").<br />
<br />
== Configuring WeBWorK ==<br />
<br />
=== Making Copies of the Distribution Configuration Files ===<br />
<br />
Before configuring the system, you must make local copies of the <code>site.conf</code> and <code>localOverrides.conf</code> configuration files, located in <code>/opt/webwork/webwork2/conf/</code> . <br />
<br />
$ cd /opt/webwork/webwork2/conf<br />
$ cp site.conf.dist site.conf<br />
$ cp localOverrides.conf.dist localOverrides.conf<br />
<br />
=== System 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 instructors 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 />
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 />
==== Edit the site.conf file ====<br />
Now edit <code>site.conf</code><br />
<br />
$ cd /opt/webwork/webwork2/conf<br />
$ nano site.conf<br />
<br />
First we have to add information about the Apache2 server setup. <br />
Search for <code>server_root_url</code> and edit the line so that it reads:<br />
<br />
$server_root_url = 'http://yourserver.yourschool.edu';<br />
<br />
where of course you should edit <code>yourserver.yourschool.edu</code> appropriately. The "http://" is important. '''If you are running a secure server (i.e., using SSL - really TLS), the url should start with https:<br />
but you should wait to make that change until after WeBWorK is up and running and you set up SSL. In that case the "https://" is important.<br />
<br />
=== Database Settings ===<br />
<br />
Search for the code <code>$database_driver</code>. Uncomment the type of database you set up (MySQL or MariaDB) and comment out the other. <br />
<br />
We need to set a password that WeBWorK uses when it communicates with the MySQL database. Note that this is not the same as the <code>&lt;mysql root password&gt;</code> which is the unused password we set when securing MySQL.<br />
Search for <code>database_password</code> and replace the line<br />
$database_password = "passwordRW";<br />
by <br />
$database_password = 'database_password';<br />
where of course you should replace "database_password" with your own password but do use the single quotes. Remember this password as we will need it below.<br />
<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 />
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 />
'''Note:''' Some servers will need to set a value of <code>$server_apache_version</code> in <code>site.conf</code>. This setting is needed when the Apache settings disable the display of the Apache version number in Apache banner of the HTTP headers, typically by setting <code>ServerTokens Prod</code> in the Apache cponfig, as many security teams will recommend. In such cases, without a setting for this variable, WeBWorK will fail to detect that you are using Apache 2.4 and users will run into error pages reporting <code>Can't locate object method "remote_addr" via package "Apache2::Connection" at /opt/webwork/webwork2/lib/WeBWorK/Authen.pm</code> which will also appear in the Apache error.log file. The fix is to search for <code>$server_apache_version</code>, uncomment the line, and set a suitable value (currently "2.4" should work, and a fix to support settings like "2.4.29" is pending).<br />
<br />
Then save the file and Quit.<br />
<br />
=== Default Header Files ===<br />
<br />
After you have used WeBWorK for awhile, you may want to change the default header files in <code>defaults.config</code>. Search for <code>$webworkFiles{screenSnippets}{setHeader}</code> and <code>$webworkFiles{hardcopySnippets}{setHeader}</code> in <code>localOverrides.config</code>. Settings in the conf and config files affect all WeBWorK courses. You can override any setting in these conf and config files for an individual course by putting the local setting in <code>course.conf</code>.<br />
<br />
Also now there are several versions of the classlist editor, homeworkset editor, library browser and pgproblem editor. Which ones are available in a course is determined by the settings for <code>%showeditors</code> in localOverrides.conf. As above, if you want to customize what is available for an individual course (e.g. one professor may want to try out the new editors and others may not), copy the <code>%showeditors</code> structure to <code>course.conf</code> and then edit it to make available the desired editors.<br />
<br />
=== Set up the webwork database ===<br />
<br />
WeBWorK uses a single database, called <code>webwork</code>, for all courses. We will create the <code>webwork</code> database now.<br />
<br />
To do this do the following ('''before you just copy, paste and hit <code>&lt;Enter&gt;</code>''' notice that you have to replace <code>database_password</code> with the password you set when editing <code>site.conf</code> above):<br />
<br />
$ sudo mysql <br />
[sudo] password for wwadmin: <wwadmin password><br />
<br />
mysql> CREATE DATABASE webwork;<br />
mysql> CREATE USER 'webworkWrite'@'localhost' IDENTIFIED BY 'database_password';<br />
mysql> GRANT SELECT, INSERT, UPDATE, DELETE, CREATE, ALTER, DROP, LOCK TABLES ON webwork.* TO 'webworkWrite'@'localhost';<br />
mysql> exit<br />
Bye<br />
$ <br />
<br />
where as we said '''replace''' <code>database_password</code> with the password you set when editing <code>site.conf</code> above.<br />
<br />
=== Configuring Apache ===<br />
WeBWorK ships with an Apache config file that needs to linked into your Apache configuration process. The file is named <code>webwork.apache2.4-config.dist</code> and located in the <code>conf</code> directory. First, copy the file to <code>webwork.apache2-config</code>:<br />
<br />
$ cd /opt/webwork/webwork2/conf<br />
$ cp webwork.apache2.4-config.dist webwork.apache2.4-config<br />
<br />
and now link it into your Apache configuration process<br />
<br />
$ sudo su<br />
[sudo] password for wwadmin: <wwadmin password><br />
# cd /etc/apache2/conf-enabled<br />
# ln -s /opt/webwork/webwork2/conf/webwork.apache2.4-config webwork.conf<br />
<br />
The default multi-processing module (MPM) for Apache is the event module but WeBWorK uses the prefork module. So we disable the event module and enable the prefork module.<br />
<br />
# a2dismod mpm_event<br />
# a2enmod mpm_prefork<br />
<br />
Next we will make a few changes to Apache's default configuration. We need to edit two files. First we will<br />
save copies of the original files. <br />
# cd /etc/apache2/<br />
# cp apache2.conf apache2.conf.bak1<br />
# cd /etc/apache2/mods-available/<br />
# cp mpm_prefork.conf mpm_prefork.conf.bak1<br />
# exit<br />
<br />
====Edit apache2.conf====<br />
<br />
$ cd /etc/apache2/<br />
$ sudo nano apache2.conf<br />
<br />
Search for the line<br />
Timeout 300<br />
and replace it by<br />
Timeout 1200 <br />
<br />
Then save the file and quit. <br />
<br />
====Edit mpm_prefork.conf====<br />
<br />
$ cd /etc/apache2/mods-available/<br />
$ sudo nano mpm_prefork.conf<br />
<br />
Search for the lines<br />
MaxRequestWorkers 150<br />
MaxConnectionsPerChild 0<br />
Which occur under <code><IfModule mpm_prefork_module></code> and replace them by<br />
# For WeBWorK a rough rule of thumb is 5 MaxRequestWorkers per 1 GB of memory<br />
MaxRequestWorkers 10<br />
MaxConnectionsPerChild 50<br />
where you should set <code>MaxRequestWorkers</code> depending on the amount of memory your server has using the above rule of thumb. Note that for <br />
very busy servers, you should observe you memory usage and adjust the above settings as necessary. Also make sure MaxSpareServers is not set too high.<br />
<br />
Then save the file and quit.<br />
<br />
Finally we copy WeBWorK's icon file <code>favicon.ico</code> to Apache's <code>www</code> directory.<br />
$ sudo cp /opt/webwork/webwork2/htdocs/favicon.ico /var/www/html<br />
[sudo] password for wwadmin: <wwadmin password><br />
<br />
Now stop and start Apache. We do it this way to make sure the MPM gets changed. <br />
<br />
$ sudo apache2ctl stop<br />
[sudo] password for wwadmin: <wwadmin password><br />
$ sudo apache2ctl start<br />
<br />
== Test your configuration ==<br />
<br />
# Test the <code>/webwork2</code> location by visiting <code>http://yourserver.yourschool.edu/webwork2</code>. You should see the WeBWorK home page with no courses listed. Actually the directory <code>/opt/webwork/courses/</code> does contain the <code>modelCourse</code> but the <code>modelCourse</code> is not a real course so you will get an error message if you try to log into it. It will be used a as model for setting up other courses. For this reason <code>/opt/webwork/courses/modelCourse/</code> contains a file named <code>hide_directory</code> and so the <code>modelCourse</code> is not visible.<br />
# Test the <code>/webwork2_files</code> location by visiting <code>http://yourserver.yourschool.edu/webwork2_files</code>. You should see the "WeBWorK Placeholder Page".<br />
# You cannot test the <code>/webwork2_course_files</code> location until you have created a course.<br />
<br />
==If Something is Wrong ==<br />
If something is wrong one of the first things to check is that the config files have been edited correctly (e.g. one time a wrapped line in <code>localOverrides.conf</code> caused me problems, another time it was a missing single quote). A quick way to check this is to do a <code>diff</code> between the edited and distributed versions and check that <code>diff</code> reports the changes you made and only those. Another thing is to look at the Apache error log which is located at <code>/var/log/apache2/error.log</code>.<br />
<br />
$ cd /etc/apache2/<br />
$ diff apache2.conf apache2.conf.bak1<br />
$ cd /opt/webwork/webwork2/conf/<br />
$ diff site.conf site.conf.dist<br />
$ diff localOverrides.conf localOverrides.conf.dist<br />
$ diff webwork.apache2.4-config webwork.apache2.4-config.dist<br />
$ tail /var/log/apache2/error.log <br />
<br />
If something is wrong and you fix it, you will have to restart Apache for the changes to take effect<br />
<br />
$ sudo service apache2 restart<br />
[sudo] password for wwadmin: <wwadmin password><br />
<br />
== Create the admin Course ==<br />
<br />
[[Course Administration]] gives information about creating courses. Here we will give explicit instructions for doing this. (You may need to become root or use sudo to execute some of these commands.)<br />
<br />
$ cd /opt/webwork/courses<br />
$ /opt/webwork/webwork2/bin/addcourse admin --db-layout=sql_single --users=adminClasslist.lst --professors=admin<br />
$ sudo chown -R www-data:www-data admin <br />
[sudo] password for wwadmin: <wwadmin password><br />
<br />
where the last line makes the course <code>admin</code> and its subdirectories owned by the Apache server and readable/writeable by the WWADMIN user.<br />
<br />
Now goto <code>http://yourserver.yourschool.edu/webwork2</code> and should see the WeBWorK home page with <code>Course Administration</code> listed at the top. Click on it and login with Username <code>admin</code> and Password <code>admin</code> . This first thing you should do is register your new WeBWorK installation. It's quick and easy, just click on <code>Register</code>. '''IMPORTANT''' The next thing you should do is click on <code>User Settings</code> and change <code>admin</code> 's password to something more secure than <code>admin</code> . <br />
<br />
Unless you choose otherwise, users with <code>admin</code> privileges in the <code>admin</code> course (i.e. WeBWorK administrators) will automatically be added to new courses with <code>admin</code> privileges and the same password as in the <code>admin</code> course. Initially the only such user is <code>admin</code> (hopefully you are not confused by the fact that the course <code>admin</code> has a user named <code>admin</code>). It's usually convenient make yourself a WeBWorK administrator. To do this (assuming you are logged in as <code>admin</code> to the <code>admin</code> course at <code>http://yourserver.yourschool.edu/webwork2/admin</code> )<br />
# Click on <code>Classlist Editor</code> in the left panel<br />
# Click the <code>Add</code> tag and click <code>Take Action!</code><br />
# Enter the appropriate information (you can use your <code>Login Name</code> as the <code>Student ID</code> if you want and also you can leave the last three items blank) and click <code>Add Students</code><br />
# Click on <code>Classlist Editor</code> in the left panel again<br />
# When you enter a new student, by default their <code>Student ID</code> is used as their password. We'll change this now.<br />
# Select yourself with a check mark and click the <code>Password</code> tag and click <code>Take Action!</code>. (Note as a safely mechanism you can not change the password for the user you are logged in as, currently <code>admin</code>, this way) <br />
# Enter the password and then click <code>Take Action!</code><br />
# Finally give yourself <code>admin</code> privileges by selecting yourself with a check mark, clicking the <code>Edit</code> tag and then clicking <code>Take Action!</code> (or by just clicking on the "pencil" next to your login name which is a much faster way to edit classlist data for a single user)<br />
# Now at the far right change <code>Permission Level</code> from <code>student</code> to <code>admin</code><br />
# Then click <code>Take Action!</code><br />
<br />
At some point you will probably want to hide the <code>admin</code> course so that it is not listed on the WeBWorK home page. As we noted above the <code>modelCourse</code>, which is already hidden, is not a real course so you will get an error message if you try to log into it. This is a good reason to hide it. The <code>modelCourse</code> is very useful as a model (hence its name) for setting up other courses. The <code>admin</code> course is used for administering WeBWorK and even though regular users can not log into it (you did change the <code>admin</code> password, didn't you!!), it a little bit cleaner and safer to hide it from prying eyes. <br />
To hide (or unhide) a course select <code>Hide Inactive courses</code> in the admin course and follow the directions. When hidden a course will not show up in the courses list on the WeBWorK home page. It will still appear in the Course Administration listing. If you do this you will still be able to access the <code>admin</code> course using the URL <code>http://yourserver.yourschool.edu/webwork2/admin</code> but you will not see a link for it on the WeBWorK home page <code>http://yourserver.yourschool.edu/webwork2</code> . <br />
<br />
<br />
Now goto <code>http://yourserver.yourschool.edu/webwork2</code> and no course will be listed.<br />
<br />
==Checking for and Installing Hotfixes==<br />
<br />
The following commands show you how to check for and install bug fixes. '''Important Note:''' These commands check and retrieve the master branch which gives the latest stable release of the software package (webwork2, pg, etc.) with bug fixes. If a stable release newer than 2.15 exists for webwork2 and/or pg, that will be checked and retrieved which is probably not what you want. Please check before updating. The best way to do that is to look at https://github.com/openwebwork/webwork2/blob/master/VERSION and https://github.com/openwebwork/pg/blob/master/VERSION.<br />
<br />
To check if there are bug fixes, do the following. <br />
===Updating the webwork2 code===<br />
<br />
First we check for updates to the webwork2 code:<br />
cd /opt/webwork/webwork2/<br />
git remote show origin<br />
This will print several lines of data, but the last line will tell you if your copy is up to date or out of date. If it is out of date, run<br />
git pull origin and restart apache2.<br />
<br />
===Updating the pg code===<br />
<br />
Now check for updates to the pg code:<br />
cd /opt/webwork/pg/<br />
git remote show origin<br />
This will print several lines of data, but the last line will tell you if your copy is up to date or out of date. If it is out of date, run<br />
git pull origin<br />
and restart apache2.<br />
<br />
===Restart apache2===<br />
<br />
'''Important:''' After updating either webwork2 or pg, you have to restart apache2<br />
$ sudo apache2ctl restart<br />
password:<wwadmin password><br />
<br />
===Updating the OPL===<br />
<br />
The following assumes you have already installed the OPL. For that see [[#Install the Open Problem Library]] below.<br />
Now check for updates to the Open Problem Library:<br />
cd /opt/webwork/libraries/webwork-open-problem-library<br />
git remote show origin<br />
This will print several lines of data, but the last line will tell you if your copy is up to date or out of date. If it is out of date, run<br />
git pull origin<br />
Then rerun the <code>OPL-update</code> script. Updating the OPL is pretty much risk free since changes usually involve only a relatively small <br />
number of individual problems and the vast majority of problems remain unchanged. Updating the OPL does not require restarting apache2.<br />
<br />
$ OPL-update<br />
<br />
== Starting and Stopping Apache and MySQL ==<br />
If you make changes to the system, you will have to restart <code>apache2</code> before the changes take effect. On rare occasions you may need to restart <code>MySQL</code>. <br />
=== Starting and Stopping Apache ===<br />
You have to run these commands as <code>root</code>.<br />
<br />
To start or restart (i.e. stop and then start) the <code>apache2</code> webserver run the command <br />
$ sudo apache2ctl graceful<br />
[sudo] password for wwadmin: <wwadmin password><br />
You can also start <code>apache2</code> by<br />
$ sudo apache2ctl start<br />
[sudo] password for wwadmin: <wwadmin password><br />
and restart it with<br />
$ sudo apache2ctl restart<br />
[sudo] password for wwadmin: <wwadmin password><br />
<code>restart</code> is less graceful but more powerful than <code>graceful</code>. Sometimes <code>graceful</code> fails to kill all <code>apache2</code> child processes. <br />
<br />
<br />
To stop the Apache webserver run the command <br />
<br />
$ sudo apache2ctl stop<br />
[sudo] password for wwadmin: <wwadmin password><br />
<br />
Stopping and then starting Apache should definitely kill all <code>apache2</code> child processes. <br />
<br />
You can also start or stop apache2 by using the <code>init.d</code> script <code>apache2</code>. Run<br />
$ sudo /etc/init.d/apache2<br />
[sudo] password for wwadmin: <wwadmin password><br />
or equivalently<br />
$ sudo service apache2<br />
[sudo] password for wwadmin: <wwadmin password><br />
<br />
and you will get a list of allowed commands (<code>start</code>, <code>stop</code>, <code>restart</code>, etc.).<br />
<br />
Finally you can use the newer <code>systemctl</code> method, e.g.<br />
sudo systemctl start apache2<br />
[sudo] password for wwadmin: <wwadmin password><br />
<br />
sudo systemctl --help <br />
will give you a list of all possible commands, the main ones being <code>start</code>, <code>stop</code>, <code>restart</code> and <code>status</code>.<br />
<br />
=== Starting and Stopping MySQL===<br />
You have to run these commands as <code>root</code>.<br />
<br />
To start the <code>MySQL</code> server run the command <br />
<br />
$ /etc/init.d/mysql start<br />
<br />
To stop the <code>MySQL</code> server run the command <br />
$ sudo /etc/init.d/mysql stop<br />
<br />
To restart the <code>MySQL</code> server run the command <br />
$ sudo /etc/init.d/mysql restart<br />
<br />
<br />
Equivalently you can use the command<br />
$ systemctl start mysql <br />
<br />
and <code>start</code> can be replaced by <code>stop</code> and <code>restart</code>. Also, <br />
<br />
$ systemctl status mysql <br />
<br />
gives information about the mysql server. <br />
<br />
$ systemctl --help <br />
will give you a list of all possible commands.<br />
<br />
=== Starting and Stopping MariaDB ===<br />
You have to run these commands as <code>root</code>.<br />
<br />
To start the <code>MariaDB</code> server run the command <br />
<br />
$ /etc/init.d/mysql start<br />
<br />
To stop the <code>MariaDB</code> server run the command <br />
$ sudo /etc/init.d/mysql stop<br />
<br />
To restart the <code> MariaDB </code> server run the command <br />
$ sudo /etc/init.d/mysql restart<br />
<br />
<br />
Equivalently you can use the command<br />
$ systemctl start mariadb <br />
<br />
and <code>start</code> can be replaced by <code>stop</code> and <code>restart</code>. Also, <br />
<br />
$ systemctl status mariadb <br />
<br />
gives information about the mysql server. <br />
<br />
$ systemctl --help <br />
will give you a list of all possible commands.<br />
<br />
<br />
==Install the WeBWorK Problem Libraries ==<br />
Before we create a real course we will install the WeBWorK Problem Libraries.<br />
<br />
===Install the Open Problem Library ===<br />
The <code>Open Problem Library</code> consists of both WeBWorK problems and methods for searching and selecting problems. Also it contains as sub libraries many of the other standard libraries. We have to load a database for searching it.<br />
<br />
First we put a link to the Open Problem Library in the modelCourse so that when we create courses copying templates from the modelCourse, the OPL will be available.<br />
<br />
$ cd /opt/webwork/courses/modelCourse/templates/<br />
$ ln -s /opt/webwork/libraries/webwork-open-problem-library/OpenProblemLibrary Library<br />
<br />
Note that if the above link is not in the templates directory of a course, it will be automatically created when you open the Library Browser. However, <br />
if e.g. you haven't yet opened the Library Browser and the link is missing and you import problem sets (as we do in section [[#Test that Things are Working Properly|Test that Things are Working Properly]] below), you may see errors <br />
when viewing problems (you definitely will see errors in the Orientation set).<br />
<br />
Next we have to run the <code>OPL-update</code> script which will create the data that the Library Browser uses.<br />
<br />
$ OPL-update<br />
<br />
This has to convert a lot of data for over 37,000 problems so please be patient; it can take a long time.<br />
<br />
If at some time in the future you want to upgrade the Problem Library, the process<br />
is easy, see [[#Updating the OPL|Updating the OPL]]. Note that this is something you should do fairly often so that your library is up to date with<br />
new problems and bug fixes for old ones.<br />
<br />
===Initialize the OPL local statistics database table===<br />
Run the command<br />
$ update-OPL-statistics.pl<br />
to create a table to hold the OPL local statistics. See https://webwork.maa.org/wiki/OPL_Problem_Statistics for information.<br />
<br />
===Set up the access to the Contrib directory ===<br />
<br />
The <code>Contrib</code> directory contains contributions to the OPL that may not have been formally accepted into the main collection of OPL problems. This may be because the contribution is recent and has not yet been reviewed or because the problems are not properly tagged as is the case with the CAPA problem collection. It also contains the original versions of problems that have been accepted into the OPL (the idea being that the original authors maintain control of problems in the <code>Contrib</code> directory but problems in the OPL are controled by the editors). This step creates a button in the Library Browser which gives a direct link to the <code>Contrib</code> directory.<br />
<br />
<br />
Put a link to the Contrib directory in the <code>modelCourse</code> so that when we create courses copying templates from the <code>modelCourse</code>, the Contrib directory will be available. <br />
<br />
$ cd /opt/webwork/courses/modelCourse/templates/<br />
$ ln -s /opt/webwork/libraries/webwork-open-problem-library/Contrib Contrib<br />
<br />
If you just want to do this for individual courses, not all courses then don't put the link in the <code>modelCourse</code> above, and then do the following. Note we don't have any individual courses yet. But for example after creating <code>myTestCourse</code> below, to set up access to the <code>Contrib</code> directory from <code>myTestCourse</code>, do the following<br />
$ cd /opt/webwork/courses/myTestCourse/templates/<br />
$ sudo $ ln -s /opt/webwork/libraries/webwork-open-problem-library/Contrib Contrib<br />
[sudo] password for wwadmin: <wwadmin password><br />
<br />
===Set up the Rochester and Union Libraries ===<br />
<br />
This step is optional. It creates buttons in the Library Browser which give direct links to the Rochester and Union libraries. If you don't do this, you can find these libraries and others under the <code>OPL Directory</code> button.<br />
<br />
First we need to edit <code>localOverrides.conf</code> one last time<br />
<br />
$ cd /opt/webwork/webwork2/conf<br />
$ nano localOverrides.conf<br />
<br />
Search for <code>courseFiles{problibs}</code> and scroll down several lines to the lines<br />
# rochesterLibrary =&gt; "Rochester",<br />
# unionLibrary =&gt; "Union",<br />
Uncomment these lines (i.e. remove the <code>#</code>) so they become <br />
rochesterLibrary =&gt; "Rochester",<br />
unionLibrary =&gt; "Union",<br />
Then save the file and quit.<br />
<br />
We next put links to the Rochester and Union Libraries in the <code>modelCourse</code> so that when we create courses copying templates from the <code>modelCourse</code>, these libraries will be available. Skip this step if you usually only want to use Open Problem Library. Note that the Rochester, Union and other libraries are contained in the OPen Problem Library and are accessible from there under the <code>OPL Directory</code> button in the Library Browser. This step simply creates buttons in the Library Browser so that you can access the Rochester and Union libraries directly.<br />
<br />
$ cd /opt/webwork/courses/modelCourse/templates/<br />
$ ln -s /opt/webwork/libraries/webwork-open-problem-library/OpenProblemLibrary/Union unionLibrary<br />
$ ln -s /opt/webwork/libraries/webwork-open-problem-library/OpenProblemLibrary/Rochester rochesterLibrary<br />
<br />
If you want to put another library into the <code>modelCourse</code>, just do the analogous thing. If you just want the additional library in a particular course, add the link in the <code>templates</code> directory of that course. If you look in the directory <code>/opt/webwork/libraries/webwork-open-problem-library/OpenProblemLibrary/</code> you might find other libraries that are not yet listed in <code>global.conf</code> and these can be added in the same way as the <code>Rochester and </code><code>Union</code> libraries. Finally if you add a library with non standard symbols in the name (e.g. <code>uva-statLibrary</code>) you have to use single quotes when adding it to <code>global.conf</code>, e.g. <br><br />
&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp; <code>'uva-statLibrary' => "UVA-Stat",</code> <br><br />
It's easier to just avoid such names.<br />
<br />
===Install and Set Up the CAPA Library ===<br />
<br />
This step is optional. It installs and sets up [[CAPA Physics Problems|the CAPA Library]], which is a library of physics problems.<br />
<br />
'''Note:''' We are in the process of integrating the CAPA problems into the main distribution so some of the details below may change.<br />
<br />
Move the CAPA graphics files to the required locations and set the group.<br />
<br />
$ cd /opt/webwork/libraries/webwork-open-problem-library/Contrib/CAPA <br />
$ mv CAPA_Graphics /opt/webwork/webwork2/htdocs/<br />
$ sudo chgrp -R wwdata /opt/webwork/webwork2/htdocs/CAPA_Graphics<br />
[sudo] password for wwadmin: <wwadmin password><br />
$ sudo chmod -R g+w /opt/webwork/webwork2/htdocs/CAPA_Graphics <br />
<br />
We need to edit <code>localOverrides.conf</code> again<br />
<br />
$ cd /opt/webwork/webwork2/conf<br />
$ nano localOverrides.conf<br />
<br />
<br />
Now search for the lines<br />
$pg{specialPGEnvironmentVars}{CAPA_Tools} = "$courseDirs{templates}/Contrib/CAPA/macros/CAPA_Tools/",<br />
$pg{specialPGEnvironmentVars}{CAPA_MCTools} = "$courseDirs{templates}/Contrib/CAPA/macros/CAPA_MCTools/",<br />
$pg{specialPGEnvironmentVars}{CAPA_GraphicsDirectory} = "$courseDirs{templates}/Contrib/CAPA/CAPA_Graphics/",<br />
push @{$pg{directories}{macrosPath}},<br />
"$courseDirs{templates}/Contrib/CAPA/macros/CAPA_Tools",<br />
"$courseDirs{templates}/Contrib/CAPA/macros/CAPA_MCTools";<br />
<br />
and replace these six lines by<br />
<br />
################################################################################<br />
#Locations of CAPA resources. (Only necessary if you need to use converted CAPA problems.)<br />
################################################################################<br />
$pg{specialPGEnvironmentVars}{CAPA_Tools} = "$courseDirs{templates}/Contrib/CAPA/macros/CAPA_Tools/",<br />
$pg{specialPGEnvironmentVars}{CAPA_MCTools} = "$courseDirs{templates}/Contrib/CAPA/macros/CAPA_MCTools/",<br />
$pg{specialPGEnvironmentVars}{CAPA_GraphicsDirectory} = "$webworkDirs{htdocs}/CAPA_Graphics/";<br />
$pg{specialPGEnvironmentVars}{CAPA_Graphics_URL} = "$webworkURLs{htdocs}/CAPA_Graphics/";<br />
<br />
<br />
<br />
<br />
Then save the file and Quit.<br />
<br />
There is one final step that is needed. We have to put a link in the templates directory of every course that needs access to the CAPA Library. If you want to have every course you create have access to the CAPA Library (unlikely unless you are in a physics department) put the link in the <code>modelCourse</code>. <br />
$ cd /opt/webwork/courses/modelCourse/templates/<br />
$ ln -s /opt/webwork/libraries/webwork-open-problem-library/Contrib/CAPA/ capaLibrary<br />
<br />
More likely if you just want to do this for individual courses, not all courses then don't put the link in the <code>modelCourse</code> above, and then do the following. We don't have any yet. But for example after creating <code>myTestCourse</code> below, to set up access to the CAPA Library from <code>myTestCourse</code>, do the following<br />
$ cd /opt/webwork/courses/myTestCourse/templates/<br />
$ sudo ln -s /opt/webwork/libraries/webwork-open-problem-library/Contrib/CAPA/ capaLibrary<br />
[sudo] password for wwadmin: <wwadmin password><br />
<br />
<br />
and do the analogous thing for every course that needs access to the CAPA Library.<br />
Then to gain access to the CAPA Library from the course, simply go to the <code>Library Browser</code> and click on the <code>CAPA</code> button.<br />
<br />
<br />
<br />
==Create Your First Actual Course ==<br />
<br />
Since we have edited <code>site.conf</code> and <code>localOverrides.conf</code> and these are critical files, it would be a good idea to run<br />
$ cd /opt/webwork/webwork2/conf<br />
$ diff site.conf site.conf.dist<br />
$ diff localOverrides.conf localOverrides.conf.dist<br />
<br />
and check that you haven't made any mistakes (e.g. by introducing an inadvertent line break, etc.). If there are any mistakes, correct them. Remember that any time you change either of these files you must restart the Apache webserver in order for these changes to take effect. <br />
<br />
Since we have edited <code>global.conf</code> and haven't restarted Apache we do so now.<br />
$ sudo apache2ctl graceful<br />
password:<wwadmin password><br />
<br />
Now log into the <code>admin</code> course ( <code>http://yourserver.yourschool.edu/webwork2/admin</code> or, if you have not hidden the admin course, click on <code>Course Administration</code> on WeBWorK's home page <code>http://yourserver.yourschool.edu/webwork2/</code> ) as yourself or <code>admin</code> and <br />
# click on <code>Add Course</code><br />
# For <code>Course ID</code> enter <code>myTestCourse</code><br />
# For <code>Course Title</code> enter <code>My Test Course</code><br />
# Enter your institution<br />
# Leave <code>Add WeBWorK administrators to new course</code> checked<br />
# Add an additional instructor if you wish<br />
# Copy templates from: <code>modelCourse</code> (the default action)<br />
# Click on <code>Add Course</code><br />
# Click <code>Log into myTestCourse</code><br />
<br />
and log in either as <code>admin</code> or yourself (if you added yourself as an additional instructor above).<br />
<br />
At some point you will probably want to "hide" <code>myTestCourse</code> from general view but you already know how to do that.<br />
<br />
==Test that Things are Working Properly ==<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>.<br />
<br />
Click on <code>Hmwk Sets Editor</code> on the <code>Main Menu</code>. Then select <code>Import</code>, select <code>setDemo.def</code> from the <code>from</code> drop down list and select <code>all current users</code> from the <code>assigning this set to</code> drop down list. Then hit <code>Take Action!</code><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. If not, edit the file <code>Constants.pm</code> in the directory <code>/opt/webwork/webwork2/lib/WeBWorK</code>. Change the line <code>$WeBWorK::PG::ImageGenerator::PreserveTempFiles = 0;</code> to <code>...::PreserveTempFiles = 1;</code>. Then restart Apache and view the first couple problems or some new ones. Then look in the directory <code>/opt/webwork/webwork2/tmp/</code>. <code>cd</code> to one of the <code>ImageGenerator.../tmp/</code> directories and look at the error and log files there. When you fix the problem remember to edit <code>...::PreserveTempFiles = 1;</code> back to 0 and restart Apache or you will be saving a lot of unnecessary files. Another useful trick is to try downloading a hard copy of an assignment and then (assuming there are errors) looking at the various log files that are linked to on the output page.<br />
<br />
Note that since you probably used "admin" to login you have Permission Level "admin" so things look more complicated than if you were just a regular professor with Permission Level "professor". In particular any time you view a problem, you have the option to "Edit tags" which you probably do not want to do. If these bothers you, login as a professor (see below).<br />
<br />
Continue looking at problems to see if everything is working properly.<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 an admin 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>. If you get an error (you shouldn't) just click <code>Download Hardcopy</code> to get what was generated. Also you can see links to various informational files that are available if you run into problems (normally these files are removed if there are no errors). If you want to preserve these tmp files, set <code>$WeBWorK::ContentGenerator::Hardcopy::PreserveTempFiles</code><br />
to 1 in the file <code>Constants.pm</code> in the directory <code>/opt/webwork/webwork2/lib/WeBWorK</code> and then restart Apache. Remember to set this back to 0 after debugging.<br />
<br />
Another thing to do is to use <code>Email</code> on the <code>Main Menu</code>. Again this page is a little complicated because you can do a lot of things with it (including mail merge) but at this point just select yourself in the list to the right and hit <code>Send Email</code> at the bottom. You should receive two emails. One is the message you just sent and the other is an email with subject "WeBWorK email sent" giving information on your mailing. <br />
<br />
As a final test 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. You can also test that you can access any additional Problem Libraries that you installed. Note that if you just happen to view some statistics problems that require the R server, you will get errors (since we have not installed R --- at least not yet).<br />
<br />
'''Note:''' if when using the <code>Library Browser</code> you find that after selecting a <code>Subject</code>, you can not select a <code>Chapter</code> (and usually you will see an error from setmaker.js: /webwork2/instructorXMLHandler: e.g. Timeout or Forbidden),<br />
the most common reason is that $server_root_url has not been set "correctly" in the <code>/opt/webwork/webwork2/conf/site.conf</code> file. A common error is to use forget http:// or to use http:// when you should use https:// or to just have the wrong domain name or ip address. But sometimes "localhost" will work when the correct ip address or url will not, for example in situations when you are using a virtual machine as your host (e.g. on AWS).<br />
<br />
If all the above tests work, you can be pretty confident that WeBWorK is working properly.<br />
<br />
Go back to <code>Hmwk Sets Editor</code> on the <code>Main Menu</code>. Then select <code>Import</code>, select <code>setOrientation.def</code> from the <code>from</code> drop down list and select <code>all current users</code> from the <code>assigning this set to</code> drop down list. Then hit <code>Take Action!</code>. Then go through the Orientation problems. This is a good first set to use for introducing students to WeBWorK. Also you can Import <code>set0.def</code> and <code>setMAAtutorial.def</code> and look through those problems.<br />
<br />
If you are new to WeBWorK or even if you are a pro, you should probably add a regular student to myTestCourse and log in as that student to see what the student interface looks like. It's much simpler than the professor or admin interfaces. Also for the same reason you should probably add professor to myTestCourse and log in as that professor to see what the professor interface looks like.<br />
<br />
Click on <code>Classlist Editor</code> on the <code>Main Menu</code>.<br />
Then select <code>Add</code>, for "Add how many students?" pick 2 and hit <code>Take Action!</code>. Then add two students, say <br />
<br />
* <code>Last Name</code> "Smith", <code>First Name</code> "Jane" , <code>Student ID</code> "jsmith" and <code>Login Name</code> "jsmith"<br />
<br />
* <code>Last Name</code> "A", <code>First Name</code> "Prof" , <code>Student ID</code> "profa" and <code>Login Name</code> "profa"<br />
and make sure to select all sets to assign them to both of them. Then hit <code>Add Students</code>.<br />
<br />
Now we make "profa" a professor. Again click on <code>Classlist Editor</code> on the <code>Main Menu</code>. The fast way is to click on the "pencil" by "profa", set the "Permission Level" to "professor" and hit <code>Take Action!</code>.<br />
<br />
Jane Smith's initial password will be her <code>Student ID</code> <code>jsmith</code>. Now login as Jane Smith and play around a little. <br />
<br />
Prof A's initial password will be her <code>Student ID</code> <code>profa</code>. You should also login as Prof A and play around a little. <br />
<br />
You can also add "practice users" and login as one of those to see how you can grant partial access to your course for practice or other reasons (e.g. auditors who don't want to be graded). To do this Click on <code>Classlist Editor</code>, select <code>Import</code>, select the "demoCourse.lst" (the only classlist available at this point) and hit <code>Take Action!</code>.<br />
<br />
==Optional Configurations==<br />
*'''Optional A''' stores WeBWorK's "temporary" files in a separate partition (or directory). <br />
*'''Optional B''' installs and configures a lightweight webserver to serve static files.<br />
*'''Optional C''' configures Apache so that access to WeBWorK will be through SSL.<br />
*'''Optional D''' installs and configures the R server for statistical computing.<br />
*'''Optional E''' sets up log rotation for WeBWorK's timing log.<br />
<br />
===Implement Optional A (wwtmp)===<br />
<br />
Now is the time to implement '''Optional A''' if you choose to do so. Actually you can do this at any time and your active courses will continue to function seemingly without change. The only change behind the scenes will be that temporary files will be stored in a different location. Note that if you want to use this option but did not create <code>wwtmp</code> as a separate partition, you first have to create the directory <code>/var/www/html/wwtmp</code> with the command<br />
sudo mkdir /var/www/html/wwtmp <br />
[sudo] password for wwadmin: <wwadmin password><br />
All of WeBWorK's "temporary" files will be stored under <code>/var/www/html/wwtmp</code>. These are mostly small files such as png images of equations, pdf files, etc. that may be reused but if they are not present (e.g. if they get deleted) they will be seamlessly regenerated on the fly. There is no reason to back up such files and having them in a separate partition or directory means that it is easier and faster to back up other partitions and skip backing up unnecessary files. Even if you do not want to set up a separate partition for this, it is very convenient to at least set up a separate directory for these temporary files and we recommend that yo do so.<br />
<br />
First we set the group and permissions for the <code>wwtmp</code> directory<br />
$ sudo su<br />
[sudo] password for wwadmin: <wwadmin password><br />
# cd /var/www/html<br />
# chown wwadmin wwtmp<br />
# chgrp wwdata wwtmp<br />
# chmod ug+w wwtmp<br />
# chmod g+s wwtmp<br />
# exit<br />
$<br />
Next we have to edit <code>localOverrides.conf</code> so that WeBWorK uses the new <code>wwtmp</code> directory. Since we have a working WeBWorK system, first we make a backup copy of <code>localOverrides.conf</code>.<br />
$ cd /opt/webwork/webwork2/conf<br />
$ cp localOverrides.conf localOverrides.conf.bak1<br />
$ nano localOverrides.conf<br />
Now edit <code>localOverrides.conf</code>. Search for the line<br />
# Directory for temporary files<br />
and under that find the line<br />
# To implement, uncomment the following 6 lines:<br />
Then uncomment (i.e. remove the # symbol) from the 6 lines<br />
#$webworkDirs{htdocs_temp} = '/var/www/html/wwtmp';<br />
#$webworkURLs{htdocs_temp} = '/wwtmp';<br />
#$webworkDirs{equationCache} = "$webworkDirs{htdocs_temp}/equations";<br />
#$webworkURLs{equationCache} = "$webworkURLs{htdocs_temp}/equations";<br />
#$courseDirs{html_temp} = "/var/www/html/wwtmp/$courseName";<br />
#$courseURLs{html_temp} = "/wwtmp/$courseName";<br />
<br />
'''IMPORTANT NOTE'''. Apache 2.4 has changed the default location of the document root from <code>/var/www</code> to <br />
<code>/var/www/html</code> and we are in the process of updating the file <code>localOverrides.conf.dist</code> to reflect this.<br />
If your copy of this file does not have <code>/html</code> in the two lines above, then in addition to uncommenting the 6 lines you also have to add <code>/html</code> in two places.<br />
<br />
Then save the file and quit. If you look at the <code>wwtmp</code> directory you will find it empty but after you restart apache and then access some WeBWorK problems, you will find temporary directories and files in <code>wwtmp</code>. Remember your have to restart apache for these changes to take effect.<br />
<br />
====Using Cron Jobs to remove temporary files====<br />
<br />
It is a good idea to clean out temporary files on a regular automatic schedule. Also pdf copies of downloaded problem sets are saved in a temporary directory (<code>wwtmp/.../hardcopy</code>) so that they can be downloaded from the web. But after the download, the pdf file remains and is visible from the web if one knows the URL. For this reason we recommend deleting all such files that are over one hour old. Similarly we recommend deleting all png, gif, and html links under <code>wwtmp</code> that are over 30 days old. And finally every week we recommend deleting all equation images that are over 14 days old. The following cron jobs will accomplish this. The first is run every 30 minutes, the next three twice a month and the last one weekly on Sunday morning. These cron jobs should be run as root. We use <code>crontab</code> to edit the <code>crontab</code> file:<br />
$ sudo su<br />
[sudo] password for wwadmin: <wwadmin password><br />
# crontab -e<br />
<br />
Now add the following lines at the end of the file<br />
<br />
WEBWORK_ROOT=/opt/webwork/webwork2<br />
*/30 * * * * find /var/www/html/wwtmp/*/hardcopy/* -mmin +60 -name "*" -delete<br />
5 5 1,15 * * find /var/www/html/wwtmp/*/gif/ -mtime +30 -name "*" -delete<br />
5 5 2,16 * * find /var/www/html/wwtmp/*/png/ -mtime +30 -name "*" -delete<br />
5 5 3,17 * * find /var/www/html/wwtmp/*/html/ -mtime +30 -name "*" -delete<br />
4 5 * * 0 /opt/webwork/webwork2/bin/remove_stale_images --delete --days 14<br />
<br />
and save the file and quit<br />
# exit<br />
$<br />
<br />
===Implement Optional B (lighttpd)===<br />
<br />
As is the case for '''Optional A''' you can implement '''Optional B''' at any time and your active courses will continue to function seemingly without change. The only change behind the scenes will be that static images, pages and MathJax (if you installed it locally) will be served by a light weight web server.<br />
====Install and Configure lighttpd====<br />
First we install the light weight webserver <code>lighttpd</code><br />
<br />
Run the command <br />
$ sudo apt install lighttpd<br />
[sudo] password for wwadmin: <wwadmin password><br />
<br />
Now we configure <code>lighttpd</code>. First let's make a backup of the configuration file.<br />
<br />
<br />
$ cd /etc/lighttpd<br />
$ sudo cp lighttpd.conf lighttpd.conf.bak1<br />
[sudo] password for wwadmin: <wwadmin password><br />
<br />
Now edit <code>lighttpd.conf</code>. <br />
<br />
$ sudo nano lighttpd.conf<br />
<br />
<br />
Apache2 is listening on port 80 so we need an alternate port for lighttp to listen to. Standard alternate ports for this are usually 81, 8000, or 8080. 8080 is the only port that is listed as an official alternate at http://en.wikipedia.org/wiki/List_of_TCP_and_UDP_port_numbers . Note that in rare cases an institution may block httpd requests to port 8080. If any of your students report that they can not see graphics, they will have to request that access to requests to port 8080 be allowed.<br />
<br />
Find the line<br />
server.port = 80<br />
and replace it by<br />
server.port = 8080<br />
<br />
Now we make a few more changed that allow MathJax to run under lighttpd. You can skip these if you are running MathJax remotely. At the top of the file in the section <code> server.modules = </code>, under the line<br />
"mod_redirect",<br />
add the line<br />
"mod_setenv",<br />
Then below the closing parentheses and above the line <br />
server.document-root = "/var/www/html"<br />
add the lines<br />
setenv.add-response-header = ( "Access-Control-Allow-Origin" => "*" )<br />
alias.url = ( "/webwork2_files" => "/opt/webwork/webwork2/htdocs/" )<br />
<br />
Then save the file and quit.<br />
<br />
Now restart lighttp<br />
$sudo /etc/init.d/lighttpd restart<br />
<br />
Note that you can just run <code>/etc/init.d/lighttpd</code> to get a list of all options.<br />
<br />
====Test lighttpd====<br />
First run the command<br />
$ sudo lsof -i -P -n | grep LISTEN<br />
and check that lighttpd is listening on port 8080<br />
<br />
Now test your server by connecting to your<br />
server from a browser on a remote machine ("http://yourserver.yourschool.edu:8080/"). You should see the '''Apache2 Ubuntu Default Page''' but without a graphic for the Ubuntu Logo indicating that lighttp is running . Test the <code>/webwork2_files</code> location by visiting "http://yourserver.yourschool.edu:8080/webwork2_files</code>. You should see the "WeBWorK Placeholder Page".<br />
<br />
====Configure WeBWorK to Take Advantage of Lighttp====<br />
<br />
First let's make a backup copy of <code>localOverrides.conf </code> so that we can easily back out of these changes if necessary.<br />
<br />
$ cd /opt/webwork/webwork2/conf<br />
$ cp localOverrides.conf localOverrides.conf.bak2<br />
<br />
<br />
Now edit <code>localOverrides.conf</code>. Note that while '''Optional B''' is independent of '''Optional A''', we assume most people implementing '''Optional B''' will have already implemented '''Optional A'''. Therefore we give instructions for editing <br />
localOverrides.conf assuming that '''Optional A''' has been implemented. If this is not the case, modify the instructions below accordingly. Also replace <code>yourserver.yourschool.edu</code> with the correct address.<br />
<br />
$ nano localOverrides.conf<br />
<br />
Find the line<br />
$webworkURLs{htdocs_temp} = '/wwtmp'<br />
and replace it by<br />
#$webworkURLs{htdocs_temp} = '/wwtmp';<br />
$webworkURLs{htdocs_temp} = 'http://yourserver.yourschool.edu:8080/wwtmp';<br />
<br />
<br />
Find the line<br />
$courseURLs{html_temp} = "/wwtmp/$courseName";<br />
and replace it by<br />
#$courseURLs{html_temp} = "/wwtmp/$courseName";<br />
$courseURLs{html_temp} = "http://yourserver.yourschool.edu:8080/wwtmp/$courseName";<br />
<br />
If you installed MathJax locally under the above line add the lines<br />
# Location of MathJax script, used for the MathJax display mode.<br />
$webworkURLs{MathJax} = 'http://yourserver.yourschool.edu:8080/webwork2_files/mathjax/MathJax.js?config=TeX-MML-AM_HTMLorMML-full';<br />
If you are running MathJax remotely, '''don't add the above lines'''.<br />
<br />
Then save the file and quit.<br />
<br />
Now restart apache and lighttp.<br />
<br />
$ sudo apache2ctl graceful<br />
password:<wwadmin password><br />
$ sudo /etc/init.d/lighttpd restart<br />
<br />
====Test that Everything is Working Properly====<br />
<br />
To test things go to your test course <code>http://yourserver.yourschool.edu/webwork2/myTestCourse/</code>. Log into your course and view a problem with a graphic image (e.g. Problem 2 of the Demo set. Since you have Admin or Prof privileges, you can view sets which are not yet open). Right click on the image and click on Properties (or whatever is appropriate on your browser, e.g. copy image location) and check that the image is being served from port 8080 (something like <code>http://yourserver.yourschool.edu:8080/wwtmp/myTestCourse//gif/...</code>). <br />
<br />
If MathJax is installed locally, to test that MathJax is using lighttpd, view a problem with some typeset equations. Right click on the equation and you should see the MathJax menu which confirms MathJax is being used. Next look at the source code for the page (e.g. right click on most browsers and select "View page source") and in the source, search for mathjax.js. You should see that this is being loaded from port 8080. Obviously, if you are running MathJax remotely, you will see it is being loaded from the CDN.<br />
<br />
====Disabling Optional B (lighttpd) for a single course====<br />
<br />
If your server is hosting courses from different institutions, you may find that you need to disable using lighttpd for a single course, e.g. because the institution blocks access to port 8080. Actually since port 8080 is an "official" alternate httpd port, you should first try to get the network administrators at the institution to grant access to port 8080. Failing this, you can disable using lighttpd and instead use apache for a single course by adding the following lines to the end of the course's <code>course.conf</code> file which is located in the top level directory for the course (usually <code>/opt/webwork/courses/course_name</code>). Note that using apache instead of lighttpd will put a slightly larger load on the server. Also note that you need "admin" level privileges to edit the <code>course.conf</code> file. Instructors with only "professor" level privileges can not do this from within WeBWorK.<br />
If you are running MathJax remotely, don't add the last line.<br />
# Do not use lightppd (port 8080) for this course<br />
$webworkURLs{htdocs_temp} = '/wwtmp';<br />
$courseURLs{html_temp} = "/wwtmp/$courseName";<br />
$webworkURLs{equationCache} = "$webworkURLs{htdocs_temp}/equations";<br />
$webworkURLs{MathJax} = "$webworkURLs{htdocs}/mathjax/MathJax.js?config=TeX-MML-AM_HTMLorMML-full";<br />
'''I repeat if you are running MathJax remotely, don't add the last line above.'''<br />
<br />
===Implement Optional C (SSL)===<br />
'''Optional C''' configures apache so that access to WeBWorK will be through an encrypted connection (SSL) with an https: URL. 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. If you have implemented '''Optional B''', the non encrypted lighttpd server will be used for images, MathJax, etc. so we might have to set up the lighttpd server to run under SSL (see below).<br />
<br />
First we have to obtain an official SSL certificate or generate a self-signed one which can be used for testing purposes. If students will be using your server, it is better to obtain an official SSL certificate since using a self-signed certificate with cause warning messages to be displayed when students connect to the server.<br />
<br />
====Obtain an Official SSL Certificate====<br />
Talk to the networking group on your campus about obtaining an official certificate. You can find information on the net about certificate providers, e.g. http://www.sslshopper.com/certificate-authority-reviews.html .<br />
<br />
The certificate goes in <code>/etc/ssl/certs/</code> and the key file goes in <code>/etc/ssl/private/</code>.<br />
<br />
====Use a self-signed Certificate====<br />
<br />
When we installed the package openssh-server a self-signed certificate was automatically created. The certificate is stored at<br />
/etc/ssl/certs/ssl-cert-snakeoil.pem<br />
and the private key at<br />
/etc/ssl/private/ssl-cert-snakeoil.key<br />
<br />
This certificate and key may be regenerated manually with the following command (needs root privileges ie sudo):<br />
<br />
$ sudo make-ssl-cert generate-default-snakeoil --force-overwrite<br />
[sudo] password for wwadmin: <wwadmin password><br />
<br />
which you might want to do since I believe the original certificate is only valid for 365 days.<br />
<br />
In the instructions below we will use the provided self-signed certificate (ssl-cert-snakeoil.pem and ssl-cert-snakeoil.key) but you can also generate your own using openssh following instructions on the web. As we said above, for a production server, you should really use an official certificate.<br />
<br />
====Set up Apache to use SSL====<br />
<br />
First we enable the <code>mod_ssl</code> module<br />
$ sudo a2enmod ssl<br />
[sudo] password for wwadmin: <wwadmin password><br />
<br />
Now we have to configure Apache to use SSL.<br />
$ cd /etc/apache2/sites-available/<br />
$ sudo cp default-ssl.conf default-ssl.conf.bak1<br />
[sudo] password for wwadmin: <wwadmin password><br />
$ sudo nano default-ssl.conf<br />
<br />
Our self-signed certificate and key files are named <br />
<code>ssl-cert-snakeoil.pem</code> and <code>ssl-cert-snakeoil.key</code>. If you<br />
are using official files, put their names in the lines below. You will also have to edit the Certificate Chain, Certificate Authority and possibly other items. Instructions for doing so are beyond the scope of this document. You might look at https://www.digitalocean.com/community/tutorials/how-to-secure-apache-with-let-s-encrypt-on-ubuntu-18-04<br />
<br />
Search for the lines<br />
SSLCertificateFile /etc/ssl/certs/ssl-cert-snakeoil.pem<br />
SSLCertificateKeyFile /etc/ssl/private/ssl-cert-snakeoil.key<br />
and replace <code>ssl-cert-snakeoil.pem</code> and <code>ssl-cert-snakeoil.key</code> by the names of your certificate. Since in these instructions we are using <br />
<code>ssl-cert-snakeoil.pem</code> and <code>ssl-cert-snakeoil.key</code>, we can just leave the lines as is.<br />
<br />
Then save the file and quit. And enable <code>default-ssl.conf</code> <br />
$ sudo a2ensite default-ssl.conf<br />
[sudo] password for wwadmin: <wwadmin password><br />
Finally we restart Apache<br />
$ sudo systemctl restart apache2<br />
and test things. Connect to https://yourserver.yourschool.edu/webwork2/myTestCourse<br />
You will be asked to accept the certificate. After you do so things should work just as before except that the connection will be via https except for images, MathJax, etc. if you using lighttp. In that case, viewing math expressions in image mode should work fine but it is possible using MathJax mode will fail. We will talk about this below.<br />
<br />
====Redirect http requests to https====<br />
Assuming that everything is working, the last thing we do is set things up so that requests to http://yourserver.yourschool.edu/webwork2/ are automatically redirected to https://yourserver.yourschool.edu/webwork2/.<br />
<br />
$ cd /etc/apache2/sites-available<br />
$ sudo cp 000-default.conf 000-default.conf.bak1<br />
[sudo] password for wwadmin: <wwadmin password><br />
$ sudo nano 000-default.conf<br />
<br />
In the <br />
<VirtualHost *:80><br />
section just under the line<br />
DocumentRoot /var/www/html<br />
add the line<br />
Redirect permanent /webwork2 https://yourserver.yourschool.edu/webwork2<br />
where of course you should edit <code>yourserver.yourschool.edu</code> appropriately.<br />
Then save the file and quit.<br />
Restart Apache<br />
$ sudo service apache2 restart<br />
and try connecting to http://yourserver.yourschool.edu/webwork2/. The real connection should be through https://yourserver.yourschool.edu/webwork2/.<br />
<br />
====Check site.conf====<br />
This is important. We have to check the value of $server_root_url in webwork2/conf/site.conf to make <br />
sure it uses https (so it should read e.g. https://yourserver.yourschool.edu). If<br />
you don't do this, your may run into strange problems in the Library Browser.<br />
To check, open the Library Browser, select a subject and then click on the chapter area. If you see a drop down list of chapters, things are working properly. <br />
<br />
Now we check and edit if necessary site.conf<br />
cd /opt/webwork/webwork2/conf<br />
nano site.conf<br />
<br />
In the line<br />
$server_root_url = ...<br />
replace http by https if necessary. Then save the file, quit and restart apache<br />
sudo service apache2 restart <br />
[sudo] password for wwadmin: <wwadmin password><br />
<br />
===Configure lighttpd to use SSL===<br />
<br />
We are using lighttpd for images, pdf's and MathJax (if MathJax is installed locally) MathJax may fail (so mathematical expressions will not be displayed) if it runs under lighttpd and you do not configure lighttpd to use SSL. So let's configure lighttpd to use SSL.<br />
<br />
For lighttpd you need to concatenate the key file and the certificate file into a single pem file by running the following command.<br />
Obviously you should use the real name of your certificate and key files, not "apache.key" and "apache.crt".<br />
<br />
$ sudo su<br />
[sudo] password for wwadmin: <wwadmin password><br />
# cd /etc/ssl/private<br />
# cat apache.key ../certs/apache.crt > apache.pem<br />
# chmod 640 apache.pem<br />
# exit<br />
$<br />
<br />
If you are using official certificates,<br />
you will also have to edit the Certificate Chain, Certificate Authority and possibly other items. Instructions for doing so are beyond the scope of this document. See e.g.<br />
http://redmine.lighttpd.net/projects/lighttpd/wiki/Docs_SSL and/ or https://www.vultr.com/docs/setup-let-s-encrypt-with-lighttpd-on-ubuntu-16-04 <br />
<br />
<br />
Since we already are using the files <code>ssl-cert-snakeoil.pem</code> and <code>ssl-cert-snakeoil.key</code> for apache, we will also use them for lighttpd<br />
<br />
$ sudo cat /etc/ssl/private/ssl-cert-snakeoil.key /etc/ssl/certs/ssl-cert-snakeoil.pem >/etc/lighttpd/lighttpd.pem<br />
[sudo] password for wwadmin: <wwadmin password><br />
<br />
Now edit <code>lighttpd.conf</code>. <br />
$ cd /etc/lighttpd<br />
$ sudo cp lighttpd.conf lighttpd.conf.bak2<br />
[sudo] password for wwadmin: <wwadmin password><br />
$ sudo nano lighttpd.conf<br />
<br />
First in the list of <code>server.modules</code> at the top of the file, under the last module <code>"mod_setenv",</code>, add the module<br />
"mod_openssl",<br />
<br />
Next under the line<br />
server.port = 8080<br />
add the following<br />
$SERVER["socket"] == ":8443" {<br />
ssl.engine = "enable"<br />
ssl.pemfile = "/etc/lighttpd/lighttpd.pem"<br />
}<br />
<br />
Then save the file and quit.<br />
<br />
And restart lighttpd and check it's status<br />
<br />
$ sudo systemctl restart lighttpd<br />
[sudo] password for wwadmin: <wwadmin password><br />
$ sudo systemctl status lighttpd<br />
<br />
Sometimes when Lighttpd would not restart (or start) I just rebooted the server and everything worked. If you have difficulty you can run the command<br />
$ sudo lsof -i -P -n | grep LISTEN<br />
which will list all the ports your server is listening to. In the list you should see something similar to<br />
lighttpd 519 www-data 5u IPv4 18610 0t0 TCP *:8443 (LISTEN)<br />
<br />
<br />
====Edit localOverrides.conf</code>====<br />
$ cd /opt/webwork/webwork2/conf<br />
$ cp localOverrides.conf localOverrides.conf.bak4<br />
$ nano localOverrides.conf<br />
and replace all occurrences of 8080 by 8443 (one occurrence in three different lines). Then in these same three lines replace <code>http</code> by <code>https</code> . Obviously, you have to edit the three active lines and can ignore the commented out lines.<br />
<br />
Then save the file and quit. And restart apache<br />
$ sudo service apache2 restart<br />
[sudo] password for wwadmin: <wwadmin password><br />
<br />
and test that all is well by viewing a page with math expressions using MathJax mode.<br />
<br />
===Implement Optional D (Rserve)===<br />
<br />
Here we will install and configure the R server for statistical computing. Many statistics and probability problems (mostly contributed by faculty at the University of British Columbia) require this.<br />
<br />
See the documentation (from which we have borrowed heavily) [[R_in_WeBWorK]] for more detailed information.<br />
<br />
====Install the R server====<br />
$ sudo apt install r-cran-rserve<br />
[sudo] password for wwadmin: <wwadmin password><br />
<br />
and check that R is running<br />
$ R<br />
<br />
You should see something very similar to <br />
<br />
R version 3.6.3 (2020-02-29) -- "Holding the Windsock"<br />
Copyright (C) 2020 The R Foundation for Statistical Computing<br />
...<br />
Type 'q()' to quit R.<br />
<br />
><br />
and then quit<br />
> q()<br />
Save workspace image? [y/n/c]: n<br />
<br />
====Configure Webwork with the location of the R server====<br />
Edit the localOverrides.conf file<br />
<br />
$ cd /opt/webwork/webwork2/conf<br />
$ nano localOverrides.conf<br />
<br />
Search for the line<br />
$pg{specialPGEnvironmentVars}{DragMath}<br />
and under that line add the following<br />
<br />
################################################################################<br />
#location of the R server<br />
################################################################################<br />
$pg{specialPGEnvironmentVars}{Rserve} = {host => 'localhost'};<br />
<br />
Then save the file and Quit.<br />
<br />
====Set up Rserve to run as a daemon at system boot====<br />
<br />
This is somewhat complicated. I'm basically following instructions from https://github.com/geordielad/rserve-systemd-unit<br />
<br />
First we create a user with limited privileges to run rserve.<br />
<br />
$ sudo adduser rserveuser --system --shell=/bin/false --no-create-home --disabled-password --disabled-login<br />
<br />
<br />
Next we create a file to automatically start Rserve<br />
<br />
$ cd<br />
$ nano rserve.service<br />
Now copy and paste the following code into nano<br />
<br />
[Unit]<br />
Description=Rserve<br />
<br />
[Service]<br />
Type=forking<br />
PIDFile=/var/run/rserve/rserve.pid<br />
<br />
# Define runtime directory<br />
RuntimeDirectory=rserve<br />
RuntimeDirectoryMode=750<br />
<br />
User=rserveuser<br />
Group=nogroup<br />
<br />
ExecStart=/usr/bin/R CMD Rserve --quiet --vanilla --RS-pidfile /var/run/rserve/rserve.pid<br />
<br />
[Install]<br />
WantedBy=multi-user.target<br />
<br />
and then save the file and quit.<br />
Change the owner to root, move the file to the proper location and register it.<br />
<br />
$ sudo chown root:root rserve.service<br />
[sudo] password for wwadmin: <wwadmin password><br />
$ sudo mv rserve.service /etc/systemd/system<br />
$ sudo systemctl daemon-reload<br />
<br />
Finally we enable the service to start when the system starts<br />
<br />
$ sudo systemctl enable rserve.service<br />
<br />
====Test that things are working properly====<br />
<br />
First start Rserve manually<br />
$ sudo systemctl start rserve<br />
[sudo] password for wwadmin: <wwadmin password><br />
and run <br />
$ sudo lsof -i -P -n | grep LISTEN<br />
and you should see that Rserve is listening on port 6311<br />
<br />
Next test that WeBWorK problems using R run properly. In WeBWorK, click on <code>Library Browser</code> on the <code>Main Menu</code>. Then click <code>Open Problem Library </code> (actually it should already be selected so it will be greyed out). <br />
Now 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 />
<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 />
Finally reboot your server (to test that the Rserve starts automatically on boot up) and run <br />
$ sudo systemctl status rserve.service<br />
[sudo] password for wwadmin: <wwadmin password><br />
to check that all is well and just to be redundant <br />
$ sudo lsof -i -P -n | grep LISTEN<br />
again. Now we are sure that Rserve automatically starts when the system is booted.<br />
<br />
====Loading additional modules====<br />
This step should not be necessary unless you are writing or using WeBWorK problems that need additional resources beyond what is loaded by default. An example is using R to compute complex eigenvalues which requires the <code>Math::Complex</code> module (see https://webwork.maa.org/moodle/mod/forum/discuss.php?d=5577). The error message in such a case would be similar to <br />
Can't locate object method "make" via package "Math::Complex" (perhaps you forgot to load "Math::Complex"?) at /usr/share/perl/5.30/Math/Complex.pm line 329<br />
Died within Math::Complex::cplx called at line 351 of /usr/local/share/perl/5.30.0/Statistics/R/IO/QapEncoding.pm<br />
from within Statistics::R::IO::QapEncoding::decode called at line 236 of /usr/local/share/perl/5.30.0/Statistics/R/IO/Rserve.pm<br />
from within Statistics::R::IO::Rserve::eval called at line 26 of [PG]/lib/Rserve.pm<br />
from within Rserve::try_eval called at line 146 of [PG]/macros/RserveClient.pl<br />
from within main::rserve_eval called at line 40 of (eval 4456)<br />
<br />
First note that the required module must be installed on your server (see [[#Installing Perl Modules|Installing Perl Modules]] above). The <code>Math::Complex</code> module already is.<br />
<br />
We need to load <code>Math::Complex</code> into WeBWorK's safe compartment. For this we have to edit the localOverrides.conf file.<br />
<br />
$ cd /opt/webwork/webwork2/conf<br />
$ nano localOverrides.conf<br />
Now search for the line<br />
# Additional PG modules<br />
and under the line<br />
#push (@{${pg}{modules}}, [qw(TikZ_Image2)]);<br />
add the lines<br />
push @{$pg{modules}},<br />
[qw( Math::Complex )],<br />
; <br />
You can add as many modules as you need this way.<br />
<br />
Then save the file and Quit.<br />
<br />
===Implement Optional E (Logrotate)===<br />
Here we will set up log rotation for WeBWorK's timing log which can grow huge especially if you have a large number of users. The <code>timing.log</code> gives timing information on every action in WeBWorK (see [[WeBWorK_performance]]) and can be used to assess the performance of your server.<br />
<br />
====Create a WeBWorK configuration file for Logrotate====<br />
Logrotate’s configuration files are located in <code>/etc/logrotate.d</code>. Now we create one for WeBWorK.<br />
<br />
$ sudo nano /etc/logrotate.d/webwork<br />
<br />
Now copy and paste the following code into nano<br />
/opt/webwork/webwork2/logs/timing.log {<br />
su www-data wwdata<br />
weekly<br />
missingok<br />
rotate 15<br />
compress<br />
delaycompress<br />
notifempty<br />
}<br />
and then save the file and quit. The backup will be done weekly and we are keeping 15 weeks (approximately one semester) worth of logs. <br />
The most recent backup will not be compressed but all older ones will be. We are not explicitly creating a new <code>timing.log</code> file <br />
because WeBWorK will automatically create one if it's missing. If you want to check that it works you can run <code>logrotate</code><br />
with the configuration file (make sure you have done something with WeBWorK so that the <code>timing.log</code> is not empty):<br />
<br />
sudo logrotate -f /etc/logrotate.d/webwork<br />
[sudo] password for wwadmin: <wwadmin password><br />
<br />
Then if you look in <code>/opt/webwork/webwork2/logs</code>, you should see<br />
<br />
timing.log.1<br />
<br />
You will not see a <code>timing.log</code> file unless someone has been doing something with WeBWorK. If there is no <code>timing.log</code> file<br />
do something yourself (e.g. login to a course) and then you should see <br />
<br />
timing.log<br />
timing.log.1<br />
<br />
Now run <code>logrotate</code> again <br />
sudo logrotate -f /etc/logrotate.d/webwork<br />
[sudo] password for wwadmin: <wwadmin password><br />
and do something in WeBWorK and you should see<br />
<br />
timing.log<br />
timing.log.1<br />
timing.log.2.gz<br />
<br />
Here is what is going on. <code>timing.log.1</code> was renamed to <code>timing.log.2</code> and compressed giving <code>timing.log.2.gz</code>. <code>timing.log</code> was renamed to <code>timing.log.1</code>. <br />
And the something you (or someone else) did in WeBWorK created a new <code>timing.log</code> file. A similar procedure will happen weekly until there are a total of <br />
15 backups after which the oldest one will be deleted.<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. <br />
<br />
To fix this 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", "HTML_tth", ],<br />
<br />
Then save the file and Quit.<br />
<br />
This may or may not be addressed in a WeBWorK 15 hotfix (see [[#Checking for and Installing Hotfixes|Checking for and Installing Hotfixes]]).<br />
<br />
===UTF-8 support===<br />
WW 2.15 has some "known issues" with the UTF-8 support that arise in some WeBWorK problems. These issues are discussed in a forum discussion at: <br />
https://webwork.maa.org/moodle/mod/forum/discuss.php?d=4795. The discussion there lists pull requests by <br />
Nathan Wallach and Davide Cervone that address these issues. If you write or use WeBWorK problems that have issues with UTF-8 characters,<br />
look at that discussion. Again these issues may or may not be addressed in a WeBWorK 15 hotfix (see [[#Checking for and Installing Hotfixes|Checking for and Installing Hotfixes]]).<br />
<br />
Systems using UTF-8 problems probably need to patch /usr/share/perl5/XMLRPC/Lite.pm as explained at https://github.com/openwebwork/webwork2/issues/967#issuecomment-523941959 and may want to consider the fixes accepted in the develop branch via https://github.com/openwebwork/webwork2/pull/1089 and https://github.com/openwebwork/pg/pull/466 .<br />
<br />
==Where to go From Here ==<br />
<br />
You should play around with <code>myTestCourse</code> e.g. click on <code>Library Browser</code> and browse the <code>Problem Library</code>.<br />
<br />
Look at [[A day in the life of a WeBWorK instructor]].<br />
<br />
Read [[Course Administration]] for more information about creating courses.<br />
<br />
Under Categories below click on Administrators to see a listing of other WeBWorK documentation for system administrators.<br />
<br />
-- Main.ArnoldPizer update by Peter Staab - 19 May 2021 <br /><br />
<br />
[[Category:Administrators]]<br />
[[Category:Installation Manuals]]</div>141.154.51.251https://webwork.maa.org/mediawiki_new/index.php?title=Release_notes_for_WeBWorK_2.16&diff=20814Release notes for WeBWorK 2.162021-04-29T20:22:17Z<p>141.154.51.251: /* New PG Features */</p>
<hr />
<div>{{UnderConstruction}}<br />
<br />
== New WeBWorK Features ==<br />
* A new [[Manual_Problem_Grader|manual problem grader]] that works for all problems in homework and in gateway quizzes.<br />
* The ability to navigate between students when acting as a student<br />
[[File:StudentNavigator.png|thumb|center]]<br />
* Upgrades to the way images are shown to students (resize, zoom, drag)<br />
* Upgraded to [https://www.mathjax.org MathJax 3] from MathJax 2<br />
* As of 2.15 WeBWorK supports [http://mathquill.com MathQuill] for student input.<br />
* <code>ADD_JS_FILE</code> and <code>ADD_CSS_FILE</code> in the [https://webwork.maa.org/pod/pg/macros/PG.html#ADD_CSS_FILE PG.pl] macro.<br />
* Explanation essays (ask for a regular answer, separately ask for an explanation essay, but the essay part can be globally disabled)<br />
* Rearrange presentation order for homework and quizzes on Homework Sets page (see [https://github.com/openwebwork/webwork2/pull/1282 PR #1282])<br />
* Achievements items need not be single-use<br />
<br />
== New PG Features ==<br />
<br />
* [[TikZImages|TikZ images in problems]].<br />
* New macro [https://webwork.maa.org/pod/pg/macros/parserGraphTool.html parserGraphTool.pl] for interactive graphing problems. See also [[GraphTool|GraphTool problem technique]].<br />
* "digits" tolType (needs explanation wherever tolerance in general is explained, [https://webwork.maa.org/wiki/DigitsTolType DigitsTolType problem technique] )<br />
* <code>random_coprime</code> and <code>random_pairwise_coprime</code> methods added to [https://webwork.maa.org/pod/pg/macros/PGauxiliaryFunctions.html#random_coprime-function PGauxiliaryFunctions.pl] (Needs documentation probably in [https://webwork.maa.org/wiki/Answer_Checkers_and_the_Context]. <br />
* PGML can be used in set header files<br />
* MathObject: context classes can have aliases and alternates. (For example variable "X" could be an alias for "x".)<br />
* Improved hardcopy of PGML problems<br />
* Improvements in efficiency to [https://webwork.maa.org/pod/pg/macros/PGstatisticsmacros.html PGstatisticsmacros.pl].<br />
<br />
== Security/Advanced Features ==<br />
<br />
* Revised "WeBWorK errors" page code + error.log records<br />
* Fixes to the LTI integration, and improved debugging<br />
* Same-site Cookies<br />
* Fix applets in gateway quizzes<br />
* Additional security fixes<br />
<br />
== Things that were fixed ==<br />
Should there be a section like this? For example:<br />
* Fixed bug when Gateway questions were not in sequential order<br />
* Fix bug where, for example, `Formula("-5/(-2 x)")` would display `5/2x` for its text string<br />
<br />
== Upgrade Instructions ==<br />
* Many third party javascript libraries (jquery, jquery-ui, mathjax, codemirror, etc.) are no longer packaged with WeBWorK. These libraries are now installed via npm:<br />
# Install npm from your package manager (Ubuntu: <code>apt install npm</code> CentOS/RHEL: <code>yum install npm</code>).<br />
# Use npm to install third party javascript:<br />
> cd /opt/webwork/webwork2/htdocs<br />
> npm install<br />
* WW 2.16 requires MathJax v3. Previous versions of WW required MathJax v2 that was installed at /opt/webwork/MathJax. WW 2.16 installs MathJax via npm, so if you are upgrading an existing WW installation you may safely delete /opt/webwork/MathJax.<br />
* The following perl packages will need to be installed<br />
** HTTP::Async (on Ubuntu install the package libhttp-async-perl)<br />
** CGI::Cookie (see https://github.com/openwebwork/webwork2/pull/1149)<br />
** Archive::Zip (on Ubuntu install the package libarchive-zip-perl)<br />
* There have been some tweaks to localOverrides.conf.dist. If you have not done any customization to localOverrides.conf then you should consider replacing it with a new copy of localOverrides.conf.dist. If you have made customizations in localOverrides.conf, you should consider synchronizing them with the latest version of localOverrides.conf.dist.<br />
* Update your modelcourse with the new modelcourse.dist<br />
* The math4 theme has changed. If you use a custom theme, you may need to update your theme files to address these changes.<br />
* WeBWorK is currently not compatible with recent versions of the SQL::Abstract package, so avoid upgrading past version 1.8. WW is known to work with versions up to 1.87. (See: https://github.com/openwebwork/webwork2/issues/1236 and https://webwork.maa.org/moodle/mod/forum/discuss.php?d=5570)<br />
* If you want to allow the use of the new PGtikz.pl macro, you will need to install imagemagick (Ubuntu: <code>apt install imagemagick</code>) and modify /etc/ImageMagick-6/policy.xml and change the line near the end of the file from<br />
<code><policy domain="coder" rights="none" pattern="PDF" /></code><br />
to<br />
<code><policy domain="coder" rights="read" pattern="PDF" /></code><br />
* TikZ has two different options for a back-end program for generating images. The system administrator will have to decide which one is appropriate for their system (see https://github.com/openwebwork/webwork2/pull/1320)<br />
* TikZ requires the following two commands to be installed on your system: <code>dvisvgm</code> and <code>pdf2svg</code> (Ubuntu: <code>apt install dvisvgm pdf2svg</code>; RHEL/CentOS: <code>yum install dvisvgm</code> - pdf2svg is not currently packaged for REHEL/CentOS.)<br />
* UTF-8 support of the XML subsystem needs a local patch to be applied to /usr/share/perl5/XMLRPC/Lite.pm See: https://github.com/openwebwork/webwork2/issues/967#issuecomment-523941959. This patch can be applied with<br />
<code>sudo patch -p1 -d / < /opt/webwork/webwork2/docker-config/xmlrpc-lite-utf8-fix.patch</code><br />
<br />
== Call for Translators ==<br />
Some text has changed in the WeBWorK interface, so there are new entries that need to be translated into other languages.<br />
<br />
[[Category:Release Notes]]</div>141.154.51.251https://webwork.maa.org/mediawiki_new/index.php?title=Problem_Techniques&diff=20795Problem Techniques2021-04-28T20:08:07Z<p>141.154.51.251: /* Topics C-D */</p>
<hr />
<div><div style="background-color:#ffcccc; border:blue solid 2px; padding:5px; width:35%; float:right; margin:5px">''Any additions to the indexed snippets below should use the same format. A suggested model is provided in this [[SnippetTemplate|snippet template]].''</div><br />
<br />
== Index of Problem Coding Techniques ==<br />
<br />
<div style="background-color:#eeeeee; border:black solid 1px; padding:3px">''This index links to problem code snippets that quickly show how to accomplish each effect. Each has limited explanation that assumes a basic understanding of how PG files are written. If you want more details, please see the MathObjects documentation, POD documentation, PG macro files, and PG library files.<br />
<ul><br />
<li>[http://webwork.maa.org/wiki/Category:MathObjects MathObjects documentation] Written by Davide Cervone</li><br />
<li>[http://webwork.maa.org/pod/pg/ POD documentation] (POD - Plain Old Documentation)</li><br />
<li>[http://webwork.maa.org/viewvc/system/trunk/pg/macros/ PG macro files] Source code for pg/macros files.</li><br />
<li>[http://webwork.maa.org/viewvc/system/trunk/pg/lib/ PG library files] Source code for pg/lib files.</li><br />
</ul><br />
''</div><br />
<br />
<div style="text-align:center;font-size:smaller;"><br />
[[Author%27s_Guide|up to Author's Guide]]<br />
</div><br />
<br />
=== Topics A-B ===<br />
<br />
* [[NumericalTolerance|Accuracy Required for Numerical Answers]] <br />
* [[AdaptiveParameters|Adaptive Parameters in Answers]]<br />
* [[AddingFunctions|Adding New Functions to the Context]]<br />
* [[DynamicImages2|Adding Labels, Lines and Points to Dynamic Graphs]]<br />
* [[AlgebraicFractions|Algebraic Fractions in Student Answers]] <br />
* [[AlignedChoice|Aligned Answer Blanks]]<br />
* [[StringsInContext|Allowing Strings (Text) in Student Answers]] <br />
* [[AnswerInExponent|Answer Blank in the Exponent]]<br />
* [[AnswerFormatHelp|Answer Format Help]]<br />
* [[AnswerHints|Answer Hints]]<br />
* [[AnswerIsSolutionToEquation|Answer is a Solution to an Equation]]<br />
* [[AnyAnswerMarkedCorrect|Any Answer Marked Correct]]<br />
* [[FormulasToConstants|Antiderivatives and Indefinite Integrals]] <br />
* [[FlashPointAndGraph|Applet Example: Flash]]<br />
* [[GeoGebraApplets|Applet Example: GeoGebra]]<br />
* [[Sage_Embedding|Applet Example: Embedding Sage]]<br />
* [[DraggableProofs|Applet Example: Draggable Statements]]<br />
* [[DynamicImages2|Arrows in Dynamic Graphs]]<br />
* [[AskSage | AskSage subroutine for using Sage ]]<br />
[[#top|top of page]]<br />
<br />
=== Topics C-D ===<br />
<br />
* [[CommentsForInstructors|Comments (for Instructors) Visible in the Problem Library]] <br />
* [[ComposingFunctions|Composition of Functions as Correct Answer]]<br />
* [[CompoundProblems|Compound (Multi-part, sequential) Problems]] (<em>see also</em> [[Scaffold]])<br />
* [[ConstantsInProblems|Constants in Problems]]<br />
* [[FormulasToConstants|Constant Differences (Additive) Between Student and Correct Answers]] <br />
* [[AdaptiveParameters|Constant Differences Between Student and Correct Answers]]<br />
* [[CustomAnswerCheckers|Custom Answer Checkers]] <br />
* [[ErrorMessageCustomization|Custom Error Messages]]<br />
* [[DraggableProofs|Draggable Statements]]<br />
* [[DifferenceQuotients|Difference Quotients as Correct Answers]]<br />
* [[DifferentiatingFormulas|Differentiating Formulas]]<br />
* [[DigitsTolType|Digits TolType]]<br />
* [[DisableFunctions|Disabling Functions and Operators in Student Answers]] <br />
* [[FormulaTestPoints|Domain of Function Evaluation]] <br />
<br />
[[#top|top of page]]<br />
<br />
=== Topics E-F ===<br />
<br />
* [[EquationEvaluators|Equation Answer Evaluation (Implicit)]]<br />
* [[EquationsDefiningFunctions|Equations Defining Functions (Not Implicit)]]<br />
* [[ eval()vs.substitute() | <code>eval()</code> Versus <code>substitute()</code> ]]<br />
* [[ErrorMessageCustomization|Error Message Customization]]<br />
* [[ExtractingCoordinatesFromPoint|Extracting Coordinates of a Point]]<br />
* [[ExtractingCoordinatesFromPoint|Finding the norm of a Vector]]<br />
* [[FactoringAndExpanding|Factoring and Expanding Polynomials]]<br />
* [[FlashApplets|Flash Applets]]<br />
* [[FlashPointAndGraph|Flash Applet Point and Graph Example]]<br />
* [[FormattingCorrectAnswers: Equations |Formatting Correct Answers: Equations]]<br />
* [[FormattingCorrectAnswers: NumbersAndFormulas |Formatting Correct Answers: Numbers and Formulas]]<br />
* [[FormattingDecimals|Formatting: Decimals]]<br />
* [[AlgebraicFractions|Formatting Fractions as Student Answers]]<br />
* [[FormulaTestPoints|Formula Answer Evaluation; Limits for Evaluation]] <br />
* [[FormulaTestPoints|Formula Answer Evaluation; Test Points]]<br />
* [[ProblemsWithUnits|Formulas with Units, as Answers]]<br />
* [[VariablesOtherThanX|Formulas with Variables Other than x]] <br />
* [[AlgebraicFractions|Fractions (Algebraic) as Student Answers]]<br />
* [[AddingFunctions|Functions Added to the Context]]<br />
* [[FormulasToConstants|Function Answers Up To Additive Constants]] <br />
* [[ComposingFunctions|Function Composition as Correct Answer]]<br />
<br />
[[#top|top of page]]<br />
<br />
=== Topics G-H ===<br />
<br />
* [[DynamicImages|Graphic Images, Dynamically Generated]] <br />
* [[DynamicImages2|Graphic Images, Dynamic, with Labels, Lines and Points]] <br />
* [[DynamicImages3|Graphic Images, Dynamic, with Filled Regions]]<br />
* [[ParametricPlots|Graphic Images, with Parametric Functions]] <br />
* [[GraphsInTables|Graphic Images, Put Into Tables]]<br />
* [[StaticImages|Graphic Images, Static]] <br />
* [[TikZImages| Graphic Image, TikZ Images]]<br />
* [[ContourPlots|Graphing in 2D with Contour Plots]]<br />
* [[ContourPlot1|Graphing in 2D with Contour Plots that Have a Color Gradient]]<br />
* [[VectorFields|Graphing in 2D with Slope Fields]]<br />
* [[VectorFields2D|Graphing in 2D with Vector Fields]] <br />
* [[3DGraphsInCylindrical|Graphing in 3D with Cylindrical Coordinates]]<br />
* [[3DGraphsInRectangular|Graphing in 3D with Rectangular Coordinates]]<br />
* [[3DGraphsParametricCurves|Graphing in 3D with Parametric Curves]]<br />
* [[3DGraphsParametricSurfaces|Graphing in 3D with Parametric Surfaces (e.g., Spherical Coordinates)]]<br />
* [[3DGraphsVectorFields|Graphing in 3D with Vector Fields]]<br />
* [[GraphTool|Graph Tool, a way for students to input graphs as answers]]<br />
* [[AnswerHints|Hints in Problems]]<br />
* [[HtmlLinks|HTML Links in Problems]] <br />
<br />
[[#top|top of page]]<br />
<br />
=== Topics I-J ===<br />
<br />
* [[IntervalEvaluators|Intervals as Answers]] <br />
* [[InequalityEvaluators|Inequalities as Answers]]<br />
* [[JavaScript|JavaScript]]<br />
<br />
[[#top|top of page]]<br />
<br />
=== Topics K-L ===<br />
<br />
* [[Knowls|Knowls]]<br />
* [[DynamicImages2|Labels on Dynamically Generated Graphs]] <br />
* [[FormulaTestPoints|Limits over which Formulas are Evaluated]] <br />
* [[DynamicImages2|Lines in Dynamically Generated Graphs]] <br />
* [[MultiPartProblems|Linked Answer Blanks]] <br />
* [[LinkingProblems|Linking Successive Problems]]<br />
* [[HtmlLinks|Links to Other Web Pages]] <br />
* [[ListAnswers|Lists as Answers]] <br />
* [[FormattingDecimals|Logarithms]]<br />
<br />
[[#top|top of page]]<br />
<br />
=== Topics M-N ===<br />
<br />
* [[MatchingProblems|Matching Problems]] <br />
* [[MatchingStaticGraphs|Matching Problems That Have Static Graphic Images]]<br />
* [[MatchingDynamicGraphs|Matching Problems That Have Dynamic Graphic Images]]<br />
* [[MonthDayYear|Month, Day or Year as a problem variable]]<br />
* [[MultipleChoiceProblems|Multiple Choice Problems]]<br />
* [[GraphsInTables|Multiple Choice Problems with Graphic Images (see example 1)]]<br />
* [[MultipleSelectProblems|Multiple Select Problems (Select All That Apply or Checkbox Multiple Choice)]] <br />
* [[MultiAnswerProblems|MultiAnswer, Self Referential Problems]] <br />
* [[CompoundProblems|Multi-Part, Sequential Problems]] <br />
* [[ConstantsInProblems|Named (Numerical) Constants in Problems]]<br />
* [[ProblemsWithUnits|Numbers with Units, as Answers]]<br />
* [[NumericalTolerance|Numerical Answer Evaluation Tolerance]] <br />
* [[ConstantsInProblems|Numerical Constants in Problems]]<br />
* [[NumericalTolerance|Numerical Tolerance in Problems]] <br />
<br />
[[#top|top of page]]<br />
<br />
=== Topics O-P ===<br />
<br />
* [[AdaptiveParameters|Parameters (Adaptive) in Answers]]<br />
* [[ParametricEquationAnswers|Parametric Equations as Answers]]<br />
* [[ParametricLineAnswers|Parametric Lines as Answers]]<br />
* [[PeriodicAnswers|Periodic Answers]]<br />
* [[ImplicitPlane|Planes or Lines Defined Implicitly]]<br />
* [[ParametricPlots|Plotting Parametric Equations]] <br />
* [[DynamicImages2|Plotting Lines and Points on Dynamically Generated Graphs]] <br />
* [[DynamicImages2|Points in Dynamically Generated Graphs]] <br />
* [[PointsInAnswers|Points in Student Answers]]<br />
* [[PopUpLists|Pop-up Lists]] <br />
* [[PopUpListsLong|Pop-up Lists For Many Questions With Common Answers]]<br />
<br />
[[#top|top of page]]<br />
<br />
=== Topics Q-R ===<br />
<br />
* [[MultipleChoiceProblems|Radio Buttons and Multiple Choice Problems]]<br />
* [[RecursivelyDefinedFunctions|Recursively Defined Functions]]<br />
* [[DisableFunctions|Restricting Allowed Functions in Student Answers]] <br />
* [[DisableFunctions|Restricting Allowed Operators in Student Answers]]<br />
* [[RestrictedStudentAnswers|Restricting Student Answer Formats]]<br />
<br />
[[#top|top of page]]<br />
<br />
=== Topics S-T ===<br />
* [[Scaffold | Scaffolded (compound) problems with MultiAnswer sections]]<br />
* [[VectorFields|Slope Field Graphs]]<br />
* [[PopUpLists|Solutions for Students]]<br />
* [[StaticImages|Static Graphic Images]] <br />
* [[StepFunctions|Step Functions in Answers]]<br />
* [[StringsInContext|Strings in Student Answers]] <br />
* [[Tables|Tables in Problem Text]]<br />
* [[GraphsInTables|Tables of Graphs]]<br />
* [[FormulaTestPoints|Test Points for Formula Evaluation]] <br />
* [[StringsInContext|Text in Student Answers]]<br />
* [[TextbookSpecificMessages|Textbook Specific Messages]] <br />
* [[NumericalTolerance|Tolerance in Numerical Answers]] <br />
* [[TrigFunctionsInDegrees|Trig Functions in Degrees]]<br />
<br />
[[#top|top of page]]<br />
<br />
=== Topics U-Z ===<br />
<br />
* [[ProblemsWithUnits|Units in Problem Answers]] <br />
* [[VariablesOtherThanX|Variables Other Than x in Formulas]] <br />
* [[Vectors|Vectors in Problems]]<br />
* [[VectorParametricLines|Vector Parametric Lines as Answers]]<br />
* [[VectorValuedFunctions|Vector Valued Functions as Answers]]<br />
* [[VectorFields|Vector Field Graphs]]<br />
* [[WeightedGrader|Weighted Answer Graders]]<br />
<br />
[[#top|top of page]]<br />
<br />
[[Category:Top]]<br />
[[Category:Authors]]<br />
[[Category:Problem Techniques]]</div>141.154.51.251https://webwork.maa.org/mediawiki_new/index.php?title=Release_notes_for_WeBWorK_2.16&diff=20790Release notes for WeBWorK 2.162021-04-27T14:07:39Z<p>141.154.51.251: /* New PG Features */</p>
<hr />
<div>{{UnderConstruction}}<br />
<br />
== New WeBWorK Features ==<br />
* Upgrades to the [[Manual_Problem_Grader|manual problem grader]]<br />
* The ability to navigate between students when acting as a student<br />
[[File:StudentNavigator.png|thumb|center]]<br />
* Upgrades to the way images are shown to students (resize, zoom, drag)<br />
* Upgraded to [https://www.mathjax.org MathJax 3] from MathJax 2<br />
* As of 2.15 WeBWorK supports [http://mathquill.com MathQuill] for student input.<br />
* <code>ADD_JS_FILE</code> and <code>ADD_CSS_FILE</code> in the [https://webwork.maa.org/pod/pg/macros/PG.html#ADD_CSS_FILE PG.pl] macro.<br />
* Explanation essays (ask for a regular answer, separately ask for an explanation essay, but the essay part can be globally disabled)<br />
* Rearrange presentation order for homework and quizzes on Homework Sets page (see [https://github.com/openwebwork/webwork2/pull/1282 PR #1282])<br />
* Achievements items need not be single-use<br />
<br />
== New PG Features ==<br />
<br />
* [[TikZImages|TikZ images in problems]].<br />
* New macro [https://webwork.maa.org/pod/pg/macros/parserGraphTool.html parserGraphTool.pl] for interactive graphing problems. See also [[GraphTool|GraphTool problem technique]].<br />
* "digits" tolType (needs explanation wherever tolerance in general is explained, TODO)<br />
* `random_coprime` and `random_pairwise_coprime` macros (Needs documentation probably in [https://webwork.maa.org/wiki/Answer_Checkers_and_the_Context]. <br />
* PGML can be used in set header files<br />
* MathObject: context classes can have aliases and alternates. (For example variable "X" could be an alias for "x".)<br />
* Improved hardcopy of PGML problems<br />
* Improvements in efficiency to [https://webwork.maa.org/pod/pg/macros/PGstatisticsmacros.html PGstatisticsmacros.pl].<br />
<br />
== Security/Advanced Features ==<br />
<br />
* Revised "WeBWorK errors" page code + error.log records<br />
* Fixes to the LTI integration, and improved debugging<br />
* Same-site Cookies<br />
* Fix applets in gateway quizzes<br />
* Additional security fixes<br />
<br />
== Things that were fixed ==<br />
Should there be a section like this? For example:<br />
* Fixed bug when Gateway questions were not in sequential order<br />
* Fix bug where, for example, `Formula("-5/(-2 x)")` would display `5/2x` for its text string<br />
<br />
== Upgrade Instructions ==<br />
* Many third party javascript libraries (jquery, jquery-ui, mathjax, codemirror, etc.) are no longer packaged with WeBWorK. These libraries are now installed via npm:<br />
# Install npm from your package manager (Ubuntu: <code>apt install npm</code> CentOS/RHEL: <code>yum install npm</code>).<br />
# Use npm to install third party javascript:<br />
> cd /opt/webwork/webwork2/htdocs<br />
> npm install<br />
* WW 2.16 requires MathJax v3. Previous versions of WW required MathJax v2 that was installed at /opt/webwork/MathJax. WW 2.16 installs MathJax via npm, so if you are upgrading an existing WW installation you may safely delete /opt/webwork/MathJax.<br />
* The following perl packages will need to be installed<br />
** HTTP::Async (on Ubuntu install the package libhttp-async-perl)<br />
** CGI::Cookie (see https://github.com/openwebwork/webwork2/pull/1149)<br />
** Archive::Zip (on Ubuntu install the package libarchive-zip-perl)<br />
* There have been some tweaks to localOverrides.conf.dist. If you have not done any customization to localOverrides.conf then you should consider replacing it with a new copy of localOverrides.conf.dist. If you have made customizations in localOverrides.conf, you should consider synchronizing them with the latest version of localOverrides.conf.dist.<br />
* Update your modelcourse with the new modelcourse.dist<br />
* The math4 theme has changed. If you use a custom theme, you may need to update your theme files to address these changes.<br />
* WeBWorK is currently not compatible with recent versions of the SQL::Abstract package, so avoid upgrading past version 1.8. WW is known to work with versions up to 1.87.<br />
* If you want to allow the use of the new PGtikz.pl macro, you will need to install imagemagick (Ubuntu: <code>apt install imagemagick</code>) and modify /etc/ImageMagick-6/policy.xml and change the line near the end of the file from<br />
<code><policy domain="coder" rights="none" pattern="PDF" /></code><br />
to<br />
<code><policy domain="coder" rights="read" pattern="PDF" /></code><br />
* UTF-8 support of the XML subsystem needs a local patch to be applied to /usr/share/perl5/XMLRPC/Lite.pm See: https://github.com/openwebwork/webwork2/issues/967#issuecomment-523941959. This patch can be applied with<br />
<code>sudo patch -p1 -d / < /opt/webwork/webwork2/docker-config/xmlrpc-lite-utf8-fix.patch</code><br />
* TikZ has two different options for a back-end program for generating images. The system administrator will have to decide which one is appropriate for their system (see https://github.com/openwebwork/webwork2/pull/1320)<br />
<br />
== Call for Translators ==<br />
Some text has changed in the WeBWorK interface, so there are new entries that need to be translated into other languages.<br />
<br />
[[Category:Release Notes]]</div>141.154.51.251https://webwork.maa.org/mediawiki_new/index.php?title=Release_notes_for_WeBWorK_2.16&diff=20789Release notes for WeBWorK 2.162021-04-27T14:05:21Z<p>141.154.51.251: /* New PG Features */</p>
<hr />
<div>{{UnderConstruction}}<br />
<br />
== New WeBWorK Features ==<br />
* Upgrades to the [[Manual_Problem_Grader|manual problem grader]]<br />
* The ability to navigate between students when acting as a student<br />
[[File:StudentNavigator.png|thumb|center]]<br />
* Upgrades to the way images are shown to students (resize, zoom, drag)<br />
* Upgraded to [https://www.mathjax.org MathJax 3] from MathJax 2<br />
* As of 2.15 WeBWorK supports [http://mathquill.com MathQuill] for student input.<br />
* <code>ADD_JS_FILE</code> and <code>ADD_CSS_FILE</code> in the [https://webwork.maa.org/pod/pg/macros/PG.html#ADD_CSS_FILE PG.pl] macro.<br />
* Explanation essays (ask for a regular answer, separately ask for an explanation essay, but the essay part can be globally disabled)<br />
* Rearrange presentation order for homework and quizzes on Homework Sets page (see [https://github.com/openwebwork/webwork2/pull/1282 PR #1282])<br />
* Achievements items need not be single-use<br />
<br />
== New PG Features ==<br />
<br />
* [[TikZImages|TikZ images in problems]].<br />
* New macro [https://webwork.maa.org/pod/pg/macros/parserGraphTool.html parserGraphTool.pl] for interactive graphing problems. See also [[GraphTool|GraphTool problem technique]].<br />
* "digits" tolType (needs explanation wherever tolerance in general is explained, TODO)<br />
* `random_coprime` and `random_pairwise_coprime` macros part of <br />
* PGML can be used in set header files<br />
* MathObject: context classes can have aliases and alternates. (For example variable "X" could be an alias for "x".)<br />
* Improved hardcopy of PGML problems<br />
* Improvements in efficiency to [https://webwork.maa.org/pod/pg/macros/PGstatisticsmacros.html PGstatisticsmacros.pl].<br />
<br />
== Security/Advanced Features ==<br />
<br />
* Revised "WeBWorK errors" page code + error.log records<br />
* Fixes to the LTI integration, and improved debugging<br />
* Same-site Cookies<br />
* Fix applets in gateway quizzes<br />
* Additional security fixes<br />
<br />
== Things that were fixed ==<br />
Should there be a section like this? For example:<br />
* Fixed bug when Gateway questions were not in sequential order<br />
* Fix bug where, for example, `Formula("-5/(-2 x)")` would display `5/2x` for its text string<br />
<br />
== Upgrade Instructions ==<br />
* Many third party javascript libraries (jquery, jquery-ui, mathjax, codemirror, etc.) are no longer packaged with WeBWorK. These libraries are now installed via npm:<br />
# Install npm from your package manager (Ubuntu: <code>apt install npm</code> CentOS/RHEL: <code>yum install npm</code>).<br />
# Use npm to install third party javascript:<br />
> cd /opt/webwork/webwork2/htdocs<br />
> npm install<br />
* WW 2.16 requires MathJax v3. Previous versions of WW required MathJax v2 that was installed at /opt/webwork/MathJax. WW 2.16 installs MathJax via npm, so if you are upgrading an existing WW installation you may safely delete /opt/webwork/MathJax.<br />
* The following perl packages will need to be installed<br />
** HTTP::Async (on Ubuntu install the package libhttp-async-perl)<br />
** CGI::Cookie (see https://github.com/openwebwork/webwork2/pull/1149)<br />
** Archive::Zip (on Ubuntu install the package libarchive-zip-perl)<br />
* There have been some tweaks to localOverrides.conf.dist. If you have not done any customization to localOverrides.conf then you should consider replacing it with a new copy of localOverrides.conf.dist. If you have made customizations in localOverrides.conf, you should consider synchronizing them with the latest version of localOverrides.conf.dist.<br />
* Update your modelcourse with the new modelcourse.dist<br />
* The math4 theme has changed. If you use a custom theme, you may need to update your theme files to address these changes.<br />
* WeBWorK is currently not compatible with recent versions of the SQL::Abstract package, so avoid upgrading past version 1.8. WW is known to work with versions up to 1.87.<br />
* If you want to allow the use of the new PGtikz.pl macro, you will need to install imagemagick (Ubuntu: <code>apt install imagemagick</code>) and modify /etc/ImageMagick-6/policy.xml and change the line near the end of the file from<br />
<code><policy domain="coder" rights="none" pattern="PDF" /></code><br />
to<br />
<code><policy domain="coder" rights="read" pattern="PDF" /></code><br />
* UTF-8 support of the XML subsystem needs a local patch to be applied to /usr/share/perl5/XMLRPC/Lite.pm See: https://github.com/openwebwork/webwork2/issues/967#issuecomment-523941959. This patch can be applied with<br />
<code>sudo patch -p1 -d / < /opt/webwork/webwork2/docker-config/xmlrpc-lite-utf8-fix.patch</code><br />
* TikZ has two different options for a back-end program for generating images. The system administrator will have to decide which one is appropriate for their system (see https://github.com/openwebwork/webwork2/pull/1320)<br />
<br />
== Call for Translators ==<br />
Some text has changed in the WeBWorK interface, so there are new entries that need to be translated into other languages.<br />
<br />
[[Category:Release Notes]]</div>141.154.51.251https://webwork.maa.org/mediawiki_new/index.php?title=Release_notes_for_WeBWorK_2.16&diff=20788Release notes for WeBWorK 2.162021-04-27T13:52:05Z<p>141.154.51.251: /* New WeBWorK Features */</p>
<hr />
<div>{{UnderConstruction}}<br />
<br />
== New WeBWorK Features ==<br />
* Upgrades to the [[Manual_Problem_Grader|manual problem grader]]<br />
* The ability to navigate between students when acting as a student<br />
[[File:StudentNavigator.png|thumb|center]]<br />
* Upgrades to the way images are shown to students (resize, zoom, drag)<br />
* Upgraded to [https://www.mathjax.org MathJax 3] from MathJax 2<br />
* As of 2.15 WeBWorK supports [http://mathquill.com MathQuill] for student input.<br />
* <code>ADD_JS_FILE</code> and <code>ADD_CSS_FILE</code> in the [https://webwork.maa.org/pod/pg/macros/PG.html#ADD_CSS_FILE PG.pl] macro.<br />
* Explanation essays (ask for a regular answer, separately ask for an explanation essay, but the essay part can be globally disabled)<br />
* Rearrange presentation order for homework and quizzes on Homework Sets page (see [https://github.com/openwebwork/webwork2/pull/1282 PR #1282])<br />
* Achievements items need not be single-use<br />
<br />
== New PG Features ==<br />
<br />
* [[TikZImages|TikZ images in problems]].<br />
* New macro parserGraphTool.pl for interactive graphing problems (link to POD and documentation)<br />
* "digits" tolType (needs explanation wherever tolerance in general is explained)<br />
* `random_prime` and `random_pairwise_coprime` macros. (link to POD)<br />
* PGML can be used in set header files<br />
* MathObject: context classes can have aliases and alternates. (For example variable "X" could be an alias for "x".)<br />
* Improved hardcopy of PGML problems<br />
* Improvements in efficiency to PGstatisticsmacros.pl<br />
<br />
== Security/Advanced Features ==<br />
<br />
* Revised "WeBWorK errors" page code + error.log records<br />
* Fixes to the LTI integration, and improved debugging<br />
* Same-site Cookies<br />
* Fix applets in gateway quizzes<br />
* Additional security fixes<br />
<br />
== Things that were fixed ==<br />
Should there be a section like this? For example:<br />
* Fixed bug when Gateway questions were not in sequential order<br />
* Fix bug where, for example, `Formula("-5/(-2 x)")` would display `5/2x` for its text string<br />
<br />
== Upgrade Instructions ==<br />
* Many third party javascript libraries (jquery, jquery-ui, mathjax, codemirror, etc.) are no longer packaged with WeBWorK. These libraries are now installed via npm:<br />
# Install npm from your package manager (Ubuntu: <code>apt install npm</code> CentOS/RHEL: <code>yum install npm</code>).<br />
# Use npm to install third party javascript:<br />
> cd /opt/webwork/webwork2/htdocs<br />
> npm install<br />
* WW 2.16 requires MathJax v3. Previous versions of WW required MathJax v2 that was installed at /opt/webwork/MathJax. WW 2.16 installs MathJax via npm, so if you are upgrading an existing WW installation you may safely delete /opt/webwork/MathJax.<br />
* The following perl packages will need to be installed<br />
** HTTP::Async (on Ubuntu install the package libhttp-async-perl)<br />
** CGI::Cookie (see https://github.com/openwebwork/webwork2/pull/1149)<br />
** Archive::Zip (on Ubuntu install the package libarchive-zip-perl)<br />
* There have been some tweaks to localOverrides.conf.dist. If you have not done any customization to localOverrides.conf then you should consider replacing it with a new copy of localOverrides.conf.dist. If you have made customizations in localOverrides.conf, you should consider synchronizing them with the latest version of localOverrides.conf.dist.<br />
* Update your modelcourse with the new modelcourse.dist<br />
* The math4 theme has changed. If you use a custom theme, you may need to update your theme files to address these changes.<br />
* WeBWorK is currently not compatible with recent versions of the SQL::Abstract package, so avoid upgrading past version 1.8. WW is known to work with versions up to 1.87.<br />
* If you want to allow the use of the new PGtikz.pl macro, you will need to install imagemagick (Ubuntu: <code>apt install imagemagick</code>) and modify /etc/ImageMagick-6/policy.xml and change the line near the end of the file from<br />
<code><policy domain="coder" rights="none" pattern="PDF" /></code><br />
to<br />
<code><policy domain="coder" rights="read" pattern="PDF" /></code><br />
* UTF-8 support of the XML subsystem needs a local patch to be applied to /usr/share/perl5/XMLRPC/Lite.pm See: https://github.com/openwebwork/webwork2/issues/967#issuecomment-523941959. This patch can be applied with<br />
<code>sudo patch -p1 -d / < /opt/webwork/webwork2/docker-config/xmlrpc-lite-utf8-fix.patch</code><br />
* TikZ has two different options for a back-end program for generating images. The system administrator will have to decide which one is appropriate for their system (see https://github.com/openwebwork/webwork2/pull/1320)<br />
<br />
== Call for Translators ==<br />
Some text has changed in the WeBWorK interface, so there are new entries that need to be translated into other languages.<br />
<br />
[[Category:Release Notes]]</div>141.154.51.251https://webwork.maa.org/mediawiki_new/index.php?title=GraphTool&diff=20781GraphTool2021-04-21T21:50:26Z<p>141.154.51.251: </p>
<hr />
<div>{{UnderConstruction}}<br />
<br />
<h2>Graph Tool</h2><br />
<br />
<!-- Header for these sections -- no modification needed --> <br />
<br />
<p style="background-color:#eeeeee;border:black solid 1px;padding:3px;"><br />
This example shows how to get student input in the form of a graph (a circle) by using interactive graphing tools. <br />
</p><br />
<br />
<p style="text-align:center;"><br />
[[IndexOfProblemTechniques|Problem Techniques Index]]<br />
</p><br />
<br />
<table cellspacing="0" cellpadding="2" border="0"><br />
<br />
<tr valign="top"><br />
<th> PG problem file </th><br />
<th> Explanation </th><br />
</tr><br />
<br />
<!-- Load specialized macro files section --><br />
<br />
<tr valign="top"><br />
<td style="background-color:#ddffdd;border:black 1px dashed;"><br />
<pre><br />
DOCUMENT();<br />
loadMacros(<br />
"PGstandard.pl",<br />
"MathObjects.pl",<br />
"PGML.pl",<br />
"parserGraphTool.pl"<br />
);<br />
TEXT(beginproblem());<br />
</pre><br />
</td><br />
<td style="background-color:#ccffcc;padding:7px;"><br />
<p><br />
<b>Initialization:</b><br />
It is important to include the <tt>parseGraphTool.pl</tt> macro. <br />
</p><br />
</td><br />
</tr><br />
<br />
<!-- Setup section --><br />
<br />
<tr valign="top"><br />
<td style="background-color:#ffffdd;border:black 1px dashed;"><br />
<pre><br />
## this is the answer checker for the graph tool<br />
<br />
# This grader allows the student to graph the correct circle multiple <br />
# times. The idea is that the graph is graded based on appearance. <br />
# No matter how many times the student graphs the correct circle, <br />
# the resulting graph appears the same.<br />
<br />
$gt_checker = sub {<br />
my ($correct, $student, $ans, $value) = @_;<br />
return 0 if $ans->{isPreview};<br />
<br />
my $score = 0;<br />
my @errors;<br />
my $count = 1;<br />
<br />
# Get the center and point that define the correct circle and <br />
# compute the square of the radius.<br />
<br />
my ($cx, $cy) = $correct->[0]->extract(3)->value;<br />
my ($px, $py) = $correct->[0]->extract(4)->value;<br />
my $r_squared = ($cx - $px) ** 2 + ($cy - $py) ** 2;<br />
<br />
my $pointOnCircle = sub {<br />
my $point = shift;<br />
my ($x, $y) = $point->value;<br />
return ($x - $cx) ** 2 + ($y - $cy) ** 2 == $r_squared;<br />
};<br />
<br />
for (@$student)<br />
{<br />
my $nth = Value::List->NameForNumber($count++);<br />
<br />
# this checks if the student input matches the circle, type<br />
# (solid or dashed), the center of the circle and<br />
# checks if a point is on the circle. <br />
<br />
$score += 1, next<br />
if ($_->extract(1) eq $correct->[0]->extract(1) &&<br />
$_->extract(2) eq $correct->[0]->extract(2) &&<br />
$_->extract(3) == $correct->[0]->extract(3) &&<br />
$pointOnCircle->($_->extract(4)));<br />
<br />
# the following gives additional information to the student<br />
<br />
push(@errors, "The $nth object graphed is not a " . $correct->[0]->extract(1)),<br />
next if ($_->extract(1) ne $correct->[0]->extract(1));<br />
<br />
push(@errors, "The $nth object graphed should be a " . $correct->[0]->extract(2) . " circle."),<br />
next if ($_->extract(2) ne $correct->[0]->extract(2));<br />
<br />
push(@errors, "The $nth object graphed is incorrect.");<br />
}<br />
<br />
return ($score, @errors);<br />
};<br />
<br />
<br />
$h = non_zero_random(-5, 5);<br />
$k = non_zero_random(-5, 5);<br />
$r = random(1, 4);<br />
<br />
Context()->variables->add("y" => "Real");<br />
$circle_eq_lhs = Formula("(x-$h)^2 + (y-$k)^2")->reduce;<br />
<br />
<br />
<br />
$gt = GraphTool("{circle, solid, ($h, $k), ($h + $r, $k)}")->with(<br />
bBox => [-11, 11, 11, -11],<br />
cmpOptions => { list_checker => $gt_checker }<br />
);<br />
</pre><br />
</td><br />
<td style="background-color:#ffffcc;padding:7px;"><br />
<p><br />
<b>Setup:</b> <br />
<ul><br />
<li>The subroutine at the top is the answer checker. It checks if the student input matches the correct answer. </li><br />
<li>The variables <tt>$h, $k</tt> and <tt>$r</tt> randomly pick a center and radius of the circle.</li><br />
<li>The lines:<br />
<pre><br />
Context()->variables->add("y" => "Real");<br />
$circle_eq_lhs = Formula("(x-$h)^2 + (y-$k)^2")->reduce;<br />
</pre><br />
are used to print out nicely the equation of the circle. </li><br />
<li>The command <tt>GraphTool</tt> creates the graph tool (the axes and input buttons for the various types of graphs). The first argument is a string surrounded by {}. The arguments are:<br />
<ul><br />
<li>The type of geometric figure (circle, lines, parabolas or fills)</li><br />
<li>The type of figure (solid or dashed)</li><br />
<li>Other information about the figure. For example, with the circle, the center and another point on the circle.</li><br />
</ul><br />
</li><br />
<li>Other parameters of the <tt>GraphTool</tt> can be set using <tt>with</tt>. The following include other features:<br />
<ul><br />
<li><tt>bbox</tt>: this is an array reference of four values <tt>xmin, ymin, xmax, ymax</tt> indicating the lower left and upper right corners of the plot.</li><br />
<li><tt>cmpOptions</tt>: this is a hash of options passed to the <tt>cmp</tt> method for checking the answer. The example here:<br />
<pre><br />
cmpOptions => { list_checker => $gt_checker }<br />
</pre><br />
has the checker use the one we defined above. </li><br />
</ul></li><br />
<li>More documentation can be found at: [https://webwork.maa.org/pod/pg/macros/parserGraphTool.html]</li><br />
</ul><br />
</p><br />
<br />
</td><br />
</tr><br />
<br />
<!-- Question text section --><br />
<br />
<tr valign="top"><br />
<td style="background-color:#ffdddd;border:black 1px dashed;"><br />
<pre><br />
BEGIN_PGML<br />
Graph the circle given by the following equation.<br />
<br />
[`[$circle_eq_lhs] = [$r ** 2]`]<br />
<br />
[_]{$gt}<br />
END_PGML<br />
</pre><br />
<td style="background-color:#ffcccc;padding:7px;"><br />
<p><br />
<b>Main Text:</b><br />
This asks to graph the circle given by the equation. And the code:<br />
<pre><br />
[_]{$gt}<br />
</pre><br />
inserts the GraphTool. <br />
</p><br />
</td><br />
</tr><br />
<br />
<!-- Solution section --><br />
<br />
<tr valign="top"><br />
<td style="background-color:#eeddff;border:black 1px dashed;"><br />
<pre><br />
BEGIN_PGML_SOLUTION<br />
The equation of the circle of the form:<br />
<br />
[`[$circle_eq_lhs] = [$r ** 2]`]<br />
<br />
has a center at [`([$h],[$k])`] and radius [$r]. To enter the graph, click the circle tool, then click the center at [`([$h],[$k])`] and then click a second point that is [$r] units from the center. This is easist going left, right, up or down from the center.<br />
END_PGML_SOLUTION<br />
<br />
ENDDOCUMENT();<br />
</pre><br />
<td style="background-color:#eeccff;padding:7px;"><br />
<p><br />
This is the solution.<br />
</p><br />
</td><br />
</tr><br />
</table><br />
<br />
<p style="text-align:center;"><br />
[[IndexOfProblemTechniques|Problem Techniques Index]]<br />
</p><br />
<br />
[[Category:Problem Techniques]]<br />
<br />
<br />
<ul><br />
<li>POD documentation: [https://webwork.maa.org/pod/pg/macros/parserGraphTool.html]</li><br />
</ul></div>141.154.51.251https://webwork.maa.org/mediawiki_new/index.php?title=GraphTool&diff=20780GraphTool2021-04-21T21:47:58Z<p>141.154.51.251: </p>
<hr />
<div>{{UnderConstruction}}<br />
<br />
<h2>Graph Tool</h2><br />
<br />
<!-- Header for these sections -- no modification needed --> <br />
<br />
<p style="background-color:#eeeeee;border:black solid 1px;padding:3px;"><br />
This example shows how to get student input in the form of a graph (a circle) by using interactive graphing tools. <br />
</p><br />
<br />
<p style="text-align:center;"><br />
[[IndexOfProblemTechniques|Problem Techniques Index]]<br />
</p><br />
<br />
<table cellspacing="0" cellpadding="2" border="0"><br />
<br />
<tr valign="top"><br />
<th> PG problem file </th><br />
<th> Explanation </th><br />
</tr><br />
<br />
<!-- Load specialized macro files section --><br />
<br />
<tr valign="top"><br />
<td style="background-color:#ddffdd;border:black 1px dashed;"><br />
<pre><br />
DOCUMENT();<br />
loadMacros(<br />
"PGstandard.pl",<br />
"MathObjects.pl",<br />
"PGML.pl",<br />
"parserGraphTool.pl"<br />
);<br />
TEXT(beginproblem());<br />
</pre><br />
</td><br />
<td style="background-color:#ccffcc;padding:7px;"><br />
<p><br />
<b>Initialization:</b><br />
It is important to include the <tt>parseGraphTool.pl</tt> macro. <br />
</p><br />
</td><br />
</tr><br />
<br />
<!-- Setup section --><br />
<br />
<tr valign="top"><br />
<td style="background-color:#ffffdd;border:black 1px dashed;"><br />
<pre><br />
## this is the answer checker for the graph tool<br />
<br />
# This grader allows the student to graph the correct circle multiple <br />
# times. The idea is that the graph is graded based on appearance. <br />
# No matter how many times the student graphs the correct circle, <br />
# the resulting graph appears the same.<br />
<br />
$gt_checker = sub {<br />
my ($correct, $student, $ans, $value) = @_;<br />
return 0 if $ans->{isPreview};<br />
<br />
my $score = 0;<br />
my @errors;<br />
my $count = 1;<br />
<br />
# Get the center and point that define the correct circle and <br />
# compute the square of the radius.<br />
<br />
my ($cx, $cy) = $correct->[0]->extract(3)->value;<br />
my ($px, $py) = $correct->[0]->extract(4)->value;<br />
my $r_squared = ($cx - $px) ** 2 + ($cy - $py) ** 2;<br />
<br />
my $pointOnCircle = sub {<br />
my $point = shift;<br />
my ($x, $y) = $point->value;<br />
return ($x - $cx) ** 2 + ($y - $cy) ** 2 == $r_squared;<br />
};<br />
<br />
for (@$student)<br />
{<br />
my $nth = Value::List->NameForNumber($count++);<br />
<br />
# this checks if the student input matches the circle, type<br />
# (solid or dashed), the center of the circle and<br />
# checks if a point is on the circle. <br />
<br />
$score += 1, next<br />
if ($_->extract(1) eq $correct->[0]->extract(1) &&<br />
$_->extract(2) eq $correct->[0]->extract(2) &&<br />
$_->extract(3) == $correct->[0]->extract(3) &&<br />
$pointOnCircle->($_->extract(4)));<br />
<br />
# the following gives additional information to the student<br />
<br />
push(@errors, "The $nth object graphed is not a " . $correct->[0]->extract(1)),<br />
next if ($_->extract(1) ne $correct->[0]->extract(1));<br />
<br />
push(@errors, "The $nth object graphed should be a " . $correct->[0]->extract(2) . " circle."),<br />
next if ($_->extract(2) ne $correct->[0]->extract(2));<br />
<br />
push(@errors, "The $nth object graphed is incorrect.");<br />
}<br />
<br />
return ($score, @errors);<br />
};<br />
<br />
<br />
$h = non_zero_random(-5, 5);<br />
$k = non_zero_random(-5, 5);<br />
$r = random(1, 4);<br />
<br />
Context()->variables->add("y" => "Real");<br />
$circle_eq_lhs = Formula("(x-$h)^2 + (y-$k)^2")->reduce;<br />
<br />
<br />
<br />
$gt = GraphTool("{circle, solid, ($h, $k), ($h + $r, $k)}")->with(<br />
bBox => [-11, 11, 11, -11],<br />
cmpOptions => { list_checker => $gt_checker }<br />
);<br />
</pre><br />
</td><br />
<td style="background-color:#ffffcc;padding:7px;"><br />
<p><br />
<b>Setup:</b> <br />
<ul><br />
<li>The subroutine at the top is the answer checker. It checks if the student input matches the correct answer. </li><br />
<li>The variables <tt>$h, $k</tt> and <tt>$r</tt> randomly pick a center and radius of the circle.</li><br />
<li>The lines:<br />
<pre><br />
Context()->variables->add("y" => "Real");<br />
$circle_eq_lhs = Formula("(x-$h)^2 + (y-$k)^2")->reduce;<br />
</pre><br />
are used to print out nicely the equation of the circle. </li><br />
<li>The command <tt>GraphTool</tt> creates the graph tool (the axes and input buttons for the various types of graphs). The first argument is a string surrounded by {}. The arguments are:<br />
<ul><br />
<li>The type of geometric figure (circle, lines, parabolas or fills)</li><br />
<li>The type of figure (solid or dashed)</li><br />
<li>Other information about the figure. For example, with the circle, the center and another point on the circle.</li><br />
</ul><br />
</li><br />
<li>Other parameters of the <tt>GraphTool</tt> can be set using <tt>with</tt>. The following include other features:<br />
<ul><br />
<li><tt>bbox</tt>: this is an array reference of four values <tt>xmin, ymin, xmax, ymax</tt> indicating the lower left and upper right corners of the plot.</li><br />
<li><tt>cmpOptions</tt>: this is a hash of options passed to the <tt>cmp</tt> method for checking the answer. The example here:<br />
<pre><br />
cmpOptions => { list_checker => $gt_checker }<br />
</pre><br />
has the checker use the one we defined above. </li><br />
</ul></li><br />
</ul><br />
</p><br />
<br />
</td><br />
</tr><br />
<br />
<!-- Question text section --><br />
<br />
<tr valign="top"><br />
<td style="background-color:#ffdddd;border:black 1px dashed;"><br />
<pre><br />
BEGIN_PGML<br />
Graph the circle given by the following equation.<br />
<br />
[`[$circle_eq_lhs] = [$r ** 2]`]<br />
<br />
[_]{$gt}<br />
END_PGML<br />
</pre><br />
<td style="background-color:#ffcccc;padding:7px;"><br />
<p><br />
<b>Main Text:</b><br />
This asks to graph the circle given by the equation. And the code:<br />
<pre><br />
[_]{$gt}<br />
</pre><br />
inserts the GraphTool. <br />
</p><br />
</td><br />
</tr><br />
<br />
<!-- Solution section --><br />
<br />
<tr valign="top"><br />
<td style="background-color:#eeddff;border:black 1px dashed;"><br />
<pre><br />
BEGIN_PGML_SOLUTION<br />
The equation of the circle of the form:<br />
<br />
[`[$circle_eq_lhs] = [$r ** 2]`]<br />
<br />
has a center at [`([$h],[$k])`] and radius [$r]. To enter the graph, click the circle tool, then click the center at [`([$h],[$k])`] and then click a second point that is [$r] units from the center. This is easist going left, right, up or down from the center.<br />
END_PGML_SOLUTION<br />
<br />
ENDDOCUMENT();<br />
</pre><br />
<td style="background-color:#eeccff;padding:7px;"><br />
<p><br />
This is the solution.<br />
</p><br />
</td><br />
</tr><br />
</table><br />
<br />
<p style="text-align:center;"><br />
[[IndexOfProblemTechniques|Problem Techniques Index]]<br />
</p><br />
<br />
[[Category:Problem Techniques]]<br />
<br />
<br />
<ul><br />
<li>POD documentation: [https://webwork.maa.org/pod/pg/macros/PGtikz.html PGtikz.pl]</li><br />
<li>PG macro: [https://github.com/openwebwork/pg/blob/PG-2.16/macros/PGtikz.pl PGtikz.pl]</li><br />
<!--<li>PG macro: [https://github.com/openwebwork/pg/blob/master/macros/PGtikz.pl PGtikz.pl]</li>--><br />
</ul></div>141.154.51.251https://webwork.maa.org/mediawiki_new/index.php?title=Problem_Techniques&diff=20775Problem Techniques2021-04-17T10:37:48Z<p>141.154.51.251: /* Topics G-H */</p>
<hr />
<div><div style="background-color:#ffcccc; border:blue solid 2px; padding:5px; width:35%; float:right; margin:5px">''Any additions to the indexed snippets below should use the same format. A suggested model is provided in this [[SnippetTemplate|snippet template]].''</div><br />
<br />
== Index of Problem Coding Techniques ==<br />
<br />
<div style="background-color:#eeeeee; border:black solid 1px; padding:3px">''This index links to problem code snippets that quickly show how to accomplish each effect. Each has limited explanation that assumes a basic understanding of how PG files are written. If you want more details, please see the MathObjects documentation, POD documentation, PG macro files, and PG library files.<br />
<ul><br />
<li>[http://webwork.maa.org/wiki/Category:MathObjects MathObjects documentation] Written by Davide Cervone</li><br />
<li>[http://webwork.maa.org/pod/pg/ POD documentation] (POD - Plain Old Documentation)</li><br />
<li>[http://webwork.maa.org/viewvc/system/trunk/pg/macros/ PG macro files] Source code for pg/macros files.</li><br />
<li>[http://webwork.maa.org/viewvc/system/trunk/pg/lib/ PG library files] Source code for pg/lib files.</li><br />
</ul><br />
''</div><br />
<br />
<div style="text-align:center;font-size:smaller;"><br />
[[Author%27s_Guide|up to Author's Guide]]<br />
</div><br />
<br />
=== Topics A-B ===<br />
<br />
* [[NumericalTolerance|Accuracy Required for Numerical Answers]] <br />
* [[AdaptiveParameters|Adaptive Parameters in Answers]]<br />
* [[AddingFunctions|Adding New Functions to the Context]]<br />
* [[DynamicImages2|Adding Labels, Lines and Points to Dynamic Graphs]]<br />
* [[AlgebraicFractions|Algebraic Fractions in Student Answers]] <br />
* [[AlignedChoice|Aligned Answer Blanks]]<br />
* [[StringsInContext|Allowing Strings (Text) in Student Answers]] <br />
* [[AnswerInExponent|Answer Blank in the Exponent]]<br />
* [[AnswerFormatHelp|Answer Format Help]]<br />
* [[AnswerHints|Answer Hints]]<br />
* [[AnswerIsSolutionToEquation|Answer is a Solution to an Equation]]<br />
* [[AnyAnswerMarkedCorrect|Any Answer Marked Correct]]<br />
* [[FormulasToConstants|Antiderivatives and Indefinite Integrals]] <br />
* [[FlashPointAndGraph|Applet Example: Flash]]<br />
* [[GeoGebraApplets|Applet Example: GeoGebra]]<br />
* [[Sage_Embedding|Applet Example: Embedding Sage]]<br />
* [[DraggableProofs|Applet Example: Draggable Statements]]<br />
* [[DynamicImages2|Arrows in Dynamic Graphs]]<br />
* [[AskSage | AskSage subroutine for using Sage ]]<br />
[[#top|top of page]]<br />
<br />
=== Topics C-D ===<br />
<br />
* [[CommentsForInstructors|Comments (for Instructors) Visible in the Problem Library]] <br />
* [[ComposingFunctions|Composition of Functions as Correct Answer]]<br />
* [[CompoundProblems|Compound (Multi-part, sequential) Problems]] (<em>see also</em> [[Scaffold]])<br />
* [[ConstantsInProblems|Constants in Problems]]<br />
* [[FormulasToConstants|Constant Differences (Additive) Between Student and Correct Answers]] <br />
* [[AdaptiveParameters|Constant Differences Between Student and Correct Answers]]<br />
* [[CustomAnswerCheckers|Custom Answer Checkers]] <br />
* [[ErrorMessageCustomization|Custom Error Messages]]<br />
* [[DraggableProofs|Draggable Statements]]<br />
* [[DifferenceQuotients|Difference Quotients as Correct Answers]]<br />
* [[DifferentiatingFormulas|Differentiating Formulas]]<br />
* [[DisableFunctions|Disabling Functions and Operators in Student Answers]] <br />
* [[FormulaTestPoints|Domain of Function Evaluation]] <br />
<br />
[[#top|top of page]]<br />
<br />
=== Topics E-F ===<br />
<br />
* [[EquationEvaluators|Equation Answer Evaluation (Implicit)]]<br />
* [[EquationsDefiningFunctions|Equations Defining Functions (Not Implicit)]]<br />
* [[ eval()vs.substitute() | <code>eval()</code> Versus <code>substitute()</code> ]]<br />
* [[ErrorMessageCustomization|Error Message Customization]]<br />
* [[ExtractingCoordinatesFromPoint|Extracting Coordinates of a Point]]<br />
* [[ExtractingCoordinatesFromPoint|Finding the norm of a Vector]]<br />
* [[FactoringAndExpanding|Factoring and Expanding Polynomials]]<br />
* [[FlashApplets|Flash Applets]]<br />
* [[FlashPointAndGraph|Flash Applet Point and Graph Example]]<br />
* [[FormattingCorrectAnswers: Equations |Formatting Correct Answers: Equations]]<br />
* [[FormattingCorrectAnswers: NumbersAndFormulas |Formatting Correct Answers: Numbers and Formulas]]<br />
* [[FormattingDecimals|Formatting: Decimals]]<br />
* [[AlgebraicFractions|Formatting Fractions as Student Answers]]<br />
* [[FormulaTestPoints|Formula Answer Evaluation; Limits for Evaluation]] <br />
* [[FormulaTestPoints|Formula Answer Evaluation; Test Points]]<br />
* [[ProblemsWithUnits|Formulas with Units, as Answers]]<br />
* [[VariablesOtherThanX|Formulas with Variables Other than x]] <br />
* [[AlgebraicFractions|Fractions (Algebraic) as Student Answers]]<br />
* [[AddingFunctions|Functions Added to the Context]]<br />
* [[FormulasToConstants|Function Answers Up To Additive Constants]] <br />
* [[ComposingFunctions|Function Composition as Correct Answer]]<br />
<br />
[[#top|top of page]]<br />
<br />
=== Topics G-H ===<br />
<br />
* [[DynamicImages|Graphic Images, Dynamically Generated]] <br />
* [[DynamicImages2|Graphic Images, Dynamic, with Labels, Lines and Points]] <br />
* [[DynamicImages3|Graphic Images, Dynamic, with Filled Regions]]<br />
* [[ParametricPlots|Graphic Images, with Parametric Functions]] <br />
* [[GraphsInTables|Graphic Images, Put Into Tables]]<br />
* [[StaticImages|Graphic Images, Static]] <br />
* [[TikZImages| Graphic Image, TikZ Images]]<br />
* [[ContourPlots|Graphing in 2D with Contour Plots]]<br />
* [[ContourPlot1|Graphing in 2D with Contour Plots that Have a Color Gradient]]<br />
* [[VectorFields|Graphing in 2D with Slope Fields]]<br />
* [[VectorFields2D|Graphing in 2D with Vector Fields]] <br />
* [[3DGraphsInCylindrical|Graphing in 3D with Cylindrical Coordinates]]<br />
* [[3DGraphsInRectangular|Graphing in 3D with Rectangular Coordinates]]<br />
* [[3DGraphsParametricCurves|Graphing in 3D with Parametric Curves]]<br />
* [[3DGraphsParametricSurfaces|Graphing in 3D with Parametric Surfaces (e.g., Spherical Coordinates)]]<br />
* [[3DGraphsVectorFields|Graphing in 3D with Vector Fields]]<br />
* [[GraphTool|Graph Tool, a way for students to input graphs as answers]]<br />
* [[AnswerHints|Hints in Problems]]<br />
* [[HtmlLinks|HTML Links in Problems]] <br />
<br />
[[#top|top of page]]<br />
<br />
=== Topics I-J ===<br />
<br />
* [[IntervalEvaluators|Intervals as Answers]] <br />
* [[InequalityEvaluators|Inequalities as Answers]]<br />
* [[JavaScript|JavaScript]]<br />
<br />
[[#top|top of page]]<br />
<br />
=== Topics K-L ===<br />
<br />
* [[Knowls|Knowls]]<br />
* [[DynamicImages2|Labels on Dynamically Generated Graphs]] <br />
* [[FormulaTestPoints|Limits over which Formulas are Evaluated]] <br />
* [[DynamicImages2|Lines in Dynamically Generated Graphs]] <br />
* [[MultiPartProblems|Linked Answer Blanks]] <br />
* [[LinkingProblems|Linking Successive Problems]]<br />
* [[HtmlLinks|Links to Other Web Pages]] <br />
* [[ListAnswers|Lists as Answers]] <br />
* [[FormattingDecimals|Logarithms]]<br />
<br />
[[#top|top of page]]<br />
<br />
=== Topics M-N ===<br />
<br />
* [[MatchingProblems|Matching Problems]] <br />
* [[MatchingStaticGraphs|Matching Problems That Have Static Graphic Images]]<br />
* [[MatchingDynamicGraphs|Matching Problems That Have Dynamic Graphic Images]]<br />
* [[MonthDayYear|Month, Day or Year as a problem variable]]<br />
* [[MultipleChoiceProblems|Multiple Choice Problems]]<br />
* [[GraphsInTables|Multiple Choice Problems with Graphic Images (see example 1)]]<br />
* [[MultipleSelectProblems|Multiple Select Problems (Select All That Apply or Checkbox Multiple Choice)]] <br />
* [[MultiAnswerProblems|MultiAnswer, Self Referential Problems]] <br />
* [[CompoundProblems|Multi-Part, Sequential Problems]] <br />
* [[ConstantsInProblems|Named (Numerical) Constants in Problems]]<br />
* [[ProblemsWithUnits|Numbers with Units, as Answers]]<br />
* [[NumericalTolerance|Numerical Answer Evaluation Tolerance]] <br />
* [[ConstantsInProblems|Numerical Constants in Problems]]<br />
* [[NumericalTolerance|Numerical Tolerance in Problems]] <br />
<br />
[[#top|top of page]]<br />
<br />
=== Topics O-P ===<br />
<br />
* [[AdaptiveParameters|Parameters (Adaptive) in Answers]]<br />
* [[ParametricEquationAnswers|Parametric Equations as Answers]]<br />
* [[ParametricLineAnswers|Parametric Lines as Answers]]<br />
* [[PeriodicAnswers|Periodic Answers]]<br />
* [[ImplicitPlane|Planes or Lines Defined Implicitly]]<br />
* [[ParametricPlots|Plotting Parametric Equations]] <br />
* [[DynamicImages2|Plotting Lines and Points on Dynamically Generated Graphs]] <br />
* [[DynamicImages2|Points in Dynamically Generated Graphs]] <br />
* [[PointsInAnswers|Points in Student Answers]]<br />
* [[PopUpLists|Pop-up Lists]] <br />
* [[PopUpListsLong|Pop-up Lists For Many Questions With Common Answers]]<br />
<br />
[[#top|top of page]]<br />
<br />
=== Topics Q-R ===<br />
<br />
* [[MultipleChoiceProblems|Radio Buttons and Multiple Choice Problems]]<br />
* [[RecursivelyDefinedFunctions|Recursively Defined Functions]]<br />
* [[DisableFunctions|Restricting Allowed Functions in Student Answers]] <br />
* [[DisableFunctions|Restricting Allowed Operators in Student Answers]]<br />
* [[RestrictedStudentAnswers|Restricting Student Answer Formats]]<br />
<br />
[[#top|top of page]]<br />
<br />
=== Topics S-T ===<br />
* [[Scaffold | Scaffolded (compound) problems with MultiAnswer sections]]<br />
* [[VectorFields|Slope Field Graphs]]<br />
* [[PopUpLists|Solutions for Students]]<br />
* [[StaticImages|Static Graphic Images]] <br />
* [[StepFunctions|Step Functions in Answers]]<br />
* [[StringsInContext|Strings in Student Answers]] <br />
* [[Tables|Tables in Problem Text]]<br />
* [[GraphsInTables|Tables of Graphs]]<br />
* [[FormulaTestPoints|Test Points for Formula Evaluation]] <br />
* [[StringsInContext|Text in Student Answers]]<br />
* [[TextbookSpecificMessages|Textbook Specific Messages]] <br />
* [[NumericalTolerance|Tolerance in Numerical Answers]] <br />
* [[TrigFunctionsInDegrees|Trig Functions in Degrees]]<br />
<br />
[[#top|top of page]]<br />
<br />
=== Topics U-Z ===<br />
<br />
* [[ProblemsWithUnits|Units in Problem Answers]] <br />
* [[VariablesOtherThanX|Variables Other Than x in Formulas]] <br />
* [[Vectors|Vectors in Problems]]<br />
* [[VectorParametricLines|Vector Parametric Lines as Answers]]<br />
* [[VectorValuedFunctions|Vector Valued Functions as Answers]]<br />
* [[VectorFields|Vector Field Graphs]]<br />
* [[WeightedGrader|Weighted Answer Graders]]<br />
<br />
[[#top|top of page]]<br />
<br />
[[Category:Top]]<br />
[[Category:Authors]]<br />
[[Category:Problem Techniques]]</div>141.154.51.251https://webwork.maa.org/mediawiki_new/index.php?title=Release_notes_for_WeBWorK_2.16&diff=20642Release notes for WeBWorK 2.162021-04-07T20:54:26Z<p>141.154.51.251: /* New PG Features */</p>
<hr />
<div>{{UnderConstruction}}<br />
<br />
== New WeBWorK Features ==<br />
* Problem grader features (need a link to documentation)<br />
* [https://www.mathjax.org MathJax 3]<br />
* Should we advertise MathQuill here, even though it was in 2.15?<br />
* <code>ADD_JS_FILE</code> and <code>ADD_CSS_FILE</code> (need a link to POD)<br />
<br />
* improvements in efficiency to PGstatisticsmacros.pl<br />
* explanation essays (ask for a regular answer, separately ask for an explanation essay, but the essay part can be globally disabled)<br />
* Rearrange presentation order for homework and quizzes on Homework Sets page<br />
* Achievements items need not be single-use<br />
<br />
== New PG Features ==<br />
<br />
* [[TikZImages|TikZ images in problems]].<br />
* New macro parserGraphTool.pl for interactive graphing problems (link to POD and documentation)<br />
* "digits" tolType (needs explanation wherever tolerance in general is explained)<br />
* `random_prime` and `random_pairwise_coprime` macros. (link to POD)<br />
* PGML can be used in set header files<br />
* MathObject: context classes can have aliases and alternates. (For example variable "X" could be an alias for "x".)<br />
* Improved hardcopy of PGML problems<br />
<br />
== Security/Advanced Features ==<br />
<br />
* Revised "WeBWorK errors" page code + error.log records<br />
* LTI Improvements<br />
* Same-site Cookies<br />
* Fix applets in gateway quizzes<br />
<br />
== Things that were fixed ==<br />
Should there be a section like this? For example:<br />
* Fixed bug when Gateway questions were not in sequential order<br />
* Fix bug where, for example, `Formula("-5/(-2 x)")` would display `5/2x` for its text string<br />
<br />
== Upgrade Instructions ==<br />
* Many third party javascript libraries (jquery, jquery-ui, mathjax, codemirror, etc.) are no longer packaged with WeBWorK. These libraries are now installed via npm:<br />
# Install npm from your package manager (Ubuntu: <code>apt install npm</code> CentOS/RHEL: <code>yum install npm</code>).<br />
# Use npm to install third party javascript:<br />
> cd /opt/webwork/webwork2/htdocs<br />
> npm install<br />
* WW 2.16 requires MathJax v3. Previous versions of WW required MathJax v2 that was installed at /opt/webwork/MathJax. WW 2.16 installs MathJax via npm, so if you are upgrading an existing WW installation you may safely delete /opt/webwork/MathJax.<br />
* The following perl packages will need to be installed<br />
** HTTP::Async (on Ubuntu install the package libhttp-async-perl)<br />
** CGI::Cookie (see https://github.com/openwebwork/webwork2/pull/1149)<br />
** Archive::Zip (on Ubuntu install the package libarchive-zip-perl)<br />
* There have been some tweaks to localOverrides.conf.dist. If you have not done any customization to localOverrides.conf then you should consider replacing it with a new copy of localOverrides.conf.dist. If you have made customizations in localOverrides.conf, you should consider synchronizing them with the latest version of localOverrides.conf.dist.<br />
* The math4 theme has changed. If you use a custom theme, you may need to update your theme files to address these changes.<br />
* WeBWorK is currently not compatible with recent versions of the SQL::Abstract package, so avoid upgrading past version 1.8. WW is known to work with versions up to 1.87.<br />
* If you want to allow the use of the new PGtikz.pl macro, you will need to install imagemagick (Ubuntu: <code>apt install imagemagick</code>) and modify /etc/ImageMagick-6/policy.xml and change the line near the end of the file from<br />
<code><policy domain="coder" rights="none" pattern="PDF" /></code><br />
to<br />
<code><policy domain="coder" rights="read" pattern="PDF" /></code><br />
* UTF-8 support of the XML subsystem needs a local patch to be applied to /usr/share/perl5/XMLRPC/Lite.pm See: https://github.com/openwebwork/webwork2/issues/967#issuecomment-523941959<br />
<br />
== Call for Translators ==<br />
Some text has changed in the WeBWorK interface, so there are new entries that need to be translated into other languages.<br />
<br />
[[Category:Release Notes]]</div>141.154.51.251https://webwork.maa.org/mediawiki_new/index.php?title=Release_notes_for_WeBWorK_2.16&diff=20641Release notes for WeBWorK 2.162021-04-07T20:51:46Z<p>141.154.51.251: /* New WeBWorK Features */</p>
<hr />
<div>{{UnderConstruction}}<br />
<br />
== New WeBWorK Features ==<br />
* Problem grader features (need a link to documentation)<br />
* [https://www.mathjax.org MathJax 3]<br />
* Should we advertise MathQuill here, even though it was in 2.15?<br />
* <code>ADD_JS_FILE</code> and <code>ADD_CSS_FILE</code> (need a link to POD)<br />
<br />
* improvements in efficiency to PGstatisticsmacros.pl<br />
* explanation essays (ask for a regular answer, separately ask for an explanation essay, but the essay part can be globally disabled)<br />
* Rearrange presentation order for homework and quizzes on Homework Sets page<br />
* Achievements items need not be single-use<br />
<br />
== New PG Features ==<br />
<br />
* [[TikZImages|TikZ images in problems]].<br />
* New macro parserGraphTool.pl for interactive graphing problems<br />
* "digits" tolType (needs explanation wherever tolerance in general is explained)<br />
* `random_prime` and `random_pairwise_coprime` macros<br />
* PGML can be used in set header files<br />
* MathObject: context classes can have aliases and alternates. (For example variable "X" could be an alias for "x".)<br />
* Improved hardcopy of PGML problems<br />
<br />
== Security/Advanced Features ==<br />
<br />
* Revised "WeBWorK errors" page code + error.log records<br />
* LTI Improvements<br />
* Same-site Cookies<br />
* Fix applets in gateway quizzes<br />
<br />
== Things that were fixed ==<br />
Should there be a section like this? For example:<br />
* Fixed bug when Gateway questions were not in sequential order<br />
* Fix bug where, for example, `Formula("-5/(-2 x)")` would display `5/2x` for its text string<br />
<br />
== Upgrade Instructions ==<br />
* Many third party javascript libraries (jquery, jquery-ui, mathjax, codemirror, etc.) are no longer packaged with WeBWorK. These libraries are now installed via npm:<br />
# Install npm from your package manager (Ubuntu: <code>apt install npm</code> CentOS/RHEL: <code>yum install npm</code>).<br />
# Use npm to install third party javascript:<br />
> cd /opt/webwork/webwork2/htdocs<br />
> npm install<br />
* WW 2.16 requires MathJax v3. Previous versions of WW required MathJax v2 that was installed at /opt/webwork/MathJax. WW 2.16 installs MathJax via npm, so if you are upgrading an existing WW installation you may safely delete /opt/webwork/MathJax.<br />
* The following perl packages will need to be installed<br />
** HTTP::Async (on Ubuntu install the package libhttp-async-perl)<br />
** CGI::Cookie (see https://github.com/openwebwork/webwork2/pull/1149)<br />
** Archive::Zip (on Ubuntu install the package libarchive-zip-perl)<br />
* There have been some tweaks to localOverrides.conf.dist. If you have not done any customization to localOverrides.conf then you should consider replacing it with a new copy of localOverrides.conf.dist. If you have made customizations in localOverrides.conf, you should consider synchronizing them with the latest version of localOverrides.conf.dist.<br />
* The math4 theme has changed. If you use a custom theme, you may need to update your theme files to address these changes.<br />
* WeBWorK is currently not compatible with recent versions of the SQL::Abstract package, so avoid upgrading past version 1.8. WW is known to work with versions up to 1.87.<br />
* If you want to allow the use of the new PGtikz.pl macro, you will need to install imagemagick (Ubuntu: <code>apt install imagemagick</code>) and modify /etc/ImageMagick-6/policy.xml and change the line near the end of the file from<br />
<code><policy domain="coder" rights="none" pattern="PDF" /></code><br />
to<br />
<code><policy domain="coder" rights="read" pattern="PDF" /></code><br />
* UTF-8 support of the XML subsystem needs a local patch to be applied to /usr/share/perl5/XMLRPC/Lite.pm See: https://github.com/openwebwork/webwork2/issues/967#issuecomment-523941959<br />
<br />
== Call for Translators ==<br />
Some text has changed in the WeBWorK interface, so there are new entries that need to be translated into other languages.<br />
<br />
[[Category:Release Notes]]</div>141.154.51.251https://webwork.maa.org/mediawiki_new/index.php?title=Release_notes_for_WeBWorK_2.16&diff=20640Release notes for WeBWorK 2.162021-04-07T20:40:09Z<p>141.154.51.251: changed features to include webwork/pg features.</p>
<hr />
<div>{{UnderConstruction}}<br />
<br />
== New WeBWorK Features ==<br />
* Essay grader features<br />
* MathJax 3<br />
* Should we advertise MathQuill here, even though it was in 2.15?<br />
* <code>ADD_JS_FILE</code> and <code>ADD_CSS_FILE</code><br />
<br />
* improvements in efficiency to PGstatisticsmacros.pl<br />
* explanation essays (ask for a regular answer, separately ask for an explanation essay, but the essay part can be globally disabled)<br />
* Rearrange presentation order for homework and quizzes on Homework Sets page<br />
* Achievements items need not be single-use<br />
<br />
== New PG Features ==<br />
<br />
* [[TikZImages|TikZ images in problems]].<br />
* New macro parserGraphTool.pl for interactive graphing problems<br />
* "digits" tolType (needs explanation wherever tolerance in general is explained)<br />
* `random_prime` and `random_pairwise_coprime` macros<br />
* PGML can be used in set header files<br />
* MathObject: context classes can have aliases and alternates. (For example variable "X" could be an alias for "x".)<br />
* Improved hardcopy of PGML problems<br />
<br />
== Security/Advanced Features ==<br />
<br />
* Revised "WeBWorK errors" page code + error.log records<br />
* LTI Improvements<br />
* Same-site Cookies<br />
* Fix applets in gateway quizzes<br />
<br />
== Things that were fixed ==<br />
Should there be a section like this? For example:<br />
* Fixed bug when Gateway questions were not in sequential order<br />
* Fix bug where, for example, `Formula("-5/(-2 x)")` would display `5/2x` for its text string<br />
<br />
== Upgrade Instructions ==<br />
* Many third party javascript libraries (jquery, jquery-ui, mathjax, codemirror, etc.) are no longer packaged with WeBWorK. These libraries are now installed via npm:<br />
# Install npm from your package manager (Ubuntu: <code>apt install npm</code> CentOS/RHEL: <code>yum install npm</code>).<br />
# Use npm to install third party javascript:<br />
> cd /opt/webwork/webwork2/htdocs<br />
> npm install<br />
* WW 2.16 requires MathJax v3. Previous versions of WW required MathJax v2 that was installed at /opt/webwork/MathJax. WW 2.16 installs MathJax via npm, so if you are upgrading an existing WW installation you may safely delete /opt/webwork/MathJax.<br />
* The following perl packages will need to be installed<br />
** HTTP::Async (on Ubuntu install the package libhttp-async-perl)<br />
** CGI::Cookie (see https://github.com/openwebwork/webwork2/pull/1149)<br />
** Archive::Zip (on Ubuntu install the package libarchive-zip-perl)<br />
* There have been some tweaks to localOverrides.conf.dist. If you have not done any customization to localOverrides.conf then you should consider replacing it with a new copy of localOverrides.conf.dist. If you have made customizations in localOverrides.conf, you should consider synchronizing them with the latest version of localOverrides.conf.dist.<br />
* The math4 theme has changed. If you use a custom theme, you may need to update your theme files to address these changes.<br />
* WeBWorK is currently not compatible with recent versions of the SQL::Abstract package, so avoid upgrading past version 1.8. WW is known to work with versions up to 1.87.<br />
* If you want to allow the use of the new PGtikz.pl macro, you will need to install imagemagick (Ubuntu: <code>apt install imagemagick</code>) and modify /etc/ImageMagick-6/policy.xml and change the line near the end of the file from<br />
<code><policy domain="coder" rights="none" pattern="PDF" /></code><br />
to<br />
<code><policy domain="coder" rights="read" pattern="PDF" /></code><br />
* UTF-8 support of the XML subsystem needs a local patch to be applied to /usr/share/perl5/XMLRPC/Lite.pm See: https://github.com/openwebwork/webwork2/issues/967#issuecomment-523941959<br />
<br />
== Call for Translators ==<br />
Some text has changed in the WeBWorK interface, so there are new entries that need to be translated into other languages.<br />
<br />
[[Category:Release Notes]]</div>141.154.51.251