Installation Manual for 2.16 on Ubuntu

This article is under construction. Use the information herein with caution until this message is removed.

These instructions are a work in progress.

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

If you are just upgrading WeBWorK, especially if you already have existing WeBWorK courses, see Upgrading_WeBWorK_with_Github.

Also, it is assumed that you have an operating system installed. You can visit 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.

1 Notation
2 Install Software Packages
- 2.1 Ubuntu Software Packages
- 2.2 Installation of Other Perl Modules with cpanm
3 Apache2 Modules and mod perl
4 Installing a Database
- 4.1 Installing and Testing MySQL
- 4.2 Installing and Testing MariaDB
5 Downloading the WeBWorK System Software and Problem Libraries
6 Installing WeBWorK
7 Configuring the Shell
8 Checking Module Dependencies
- 8.1 Obtaining Javascript Libraries
- 8.2 Checking LaTeX packages
9 Configuring WeBWorK
10 Test your configuration
11 If Something is Wrong
12 Create the admin Course
13 Checking for and Installing Hotfixes
14 Starting and Stopping Apache and MySQL
15 Install the WeBWorK Problem Libraries

Notation

First some short comments on notation we will be using. We will use <key> to indicate that you should press a specific key (e.g. <Enter>, <Tab>, <F12>, etc.). Sometimes we will also use e.g. <wwadmin password> to indicate you have to enter the wwadmin password.

^ will indicate the <Ctrl> key so e.g. ^X is really shorthand for <Ctrl> <X>, i.e. press the Ctrl key and hit the X key.

Install Software Packages

Ubuntu Software Packages

On Ubuntu and other Debian linuxes, the following instructions will get needed software packages installed.

Here is the list of Ubuntu packages that need to be installed.

apache2
cpanminus
curl
dvipng
gcc
git
imagemagick
libapache2-request-perl
libarchive-zip-perl
libarray-utils-perl
libcrypt-ssleay-perl
libdatetime-perl
libdata-dump-perl
libemail-address-xs-perl
libemail-sender-perl
libexception-class-perl
libextutils-xsbuilder-perl
libfile-find-rule-perl-perl
libgd-perl
libhtml-scrubber-perl
libhttp-async-perl
libiterator-perl
libiterator-util-perl
libjson-perl
liblocale-maketext-lexicon-perl
libmime-tools-perl
libmoox-options-perl
libnet-ip-perl
libnet-ldap-perl
libnet-oauth-perl
libossp-uuid-perl
libpadwalker-perl
libpath-class-perl
libphp-serialization-perl
libpod-wsdl-perl
libsoap-lite-perl
libsql-abstract-perl
libstring-shellquote-perl
libtemplate-perl
libtext-csv-perl
libtimedate-perl
libuuid-tiny-perl
libxml-parser-easytree-perl
libxml-parser-perl
libxml-writer-perl
make
netpbm
npm
pdf2svg
preview-latex-style
texlive
texlive-latex-extra
unzip

To install all of these packages in one fell swoop, first become root:

$ sudo su
[sudo] password for wwadmin: <wwadmin password>

and then run the command (obviously you want to use cut and paste)

# apt install apache2 cpanminus curl dvipng gcc git imagemagick libapache2-request-perl \
libarchive-zip-perl libarray-utils-perl libcrypt-ssleay-perl libdancer-perl libdancer-plugin-database-perl \
libdata-dump-perl libdatetime-perl libemail-address-xs-perl libemail-sender-perl \
libexception-class-perl libextutils-xsbuilder-perl libfile-find-rule-perl-perl \
libgd-perl libhttp-async-perl libhtml-scrubber-perl libiterator-perl libiterator-util-perl libjson-perl \
liblocale-maketext-lexicon-perl libmime-tools-perl libmoox-options-perl libnet-ip-perl libnet-ldap-perl \
libnet-oauth-perl libossp-uuid-perl libpadwalker-perl libpath-class-perl \
libphp-serialization-perl libpod-wsdl-perl \
libsoap-lite-perl libsql-abstract-perl libstring-shellquote-perl libtemplate-perl \
libtext-csv-perl libtimedate-perl libuuid-tiny-perl libxml-parser-easytree-perl \
libxml-parser-perl libxml-writer-perl make netpbm npm pdf2svg \
preview-latex-style texlive texlive-latex-extra unzip

If prompted, you can always accept the default (hit <Enter>). When the process finishes, enter

# exit

to return to a regular user.

Installation of Other Perl Modules with cpanm

We will use cpanm to install other perl modules. For example, one module, Statistics::R::IO that will be needed is not in a standard package. To install this

cpanm Statistics::R::IO

Below, we will determine other perl modules that will need to be installed with this method.

Apache2 Modules and mod perl

The following loads needed apache modules.

enabling info.conf and status.conf in Ubuntu

We enable the info module. Acting as root in a terminal window enter

$ sudo su
[sudo] password for wwadmin: <wwadmin password>
# a2enmod info

Next we make a copy of the configuration files we will be editing for safekeeping.

# cd /etc/apache2/mods-available

# cp info.conf info.conf.bak1
# cp status.conf status.conf.bak1

# exit
$

Now we will edit configuration files info.conf and status.conf 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 nano. Note that you have to be root to edit these files. First we edit info.conf

$ cd /etc/apache2/mods-available
$ sudo nano info.conf
[sudo] password for wwadmin: <wwadmin password>

I suggest you allow access to server information from e.g. your department domain. To do this uncomment (i.e. remove the # from)

	Require ip 192.0.2.0/24

and then replace 192.0.2.0/24 by .math.yourschool.edu where of course you should edit .math.yourschool.edu appropriately.

Then save the file and quit (press ^X, Y, <Enter>).

Now we edit status.conf

$ cd /etc/apache2/mods-available
$ sudo nano status.conf
[sudo] password for wwadmin: <wwadmin password>

Edit the

 #Require ip 192.0.2.0/24

line just as you did for info.conf. Then save the file and quit. And restart Apache so that the above changes take effect

$ sudo systemctl restart apache2
password:<wwadmin password>

Fully Qualified Domain Name

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 hostname commands below.

Run the command

sudo hostnamectl set-hostname webwork
[sudo] password for wwadmin: <wwadmin password>

where of course you should replace webwork by whatever your server's name is.

You can check these settings by running the commands

$ hostname --fqdn

and

$ hostname

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

Note that if your server can not find its fully qualified domain name, certain tools (such as the Synaptic Package Manager) may not start.

Test Apache

Now restart Apache

$ sudo systemctl restart apache2
password:<wwadmin password>

or

$ sudo apache2ctl restart
[sudo] password for wwadmin: <wwadmin password>

or

$ sudo service apache2 restart
[sudo] password for wwadmin: <wwadmin password>

and test your server by connecting to your 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.

You can check Apache's status by connecting to "http://yourserver.yourschool.edu/server-status" from a browser on a remote machine in the math.yourschool.edu domain.

Further test Apache by connecting to "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 information about Apache. In particular under Server Settings you should see

Server Version: Apache/2.4.41 (Ubuntu) mod_apreq2-20090110/2.8.0 mod_perl/2.0.11 Perl/v5.30.0

(or something very similar) indicating that both mod_apreq2 and mod_perl are installed.

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 /var/log/apache2/error.log. In the directory /var/log/apache2/ you can "less" through the error log (less error.log), look at the last few entries (tail error.log) or run the command tail -f error.log which will display new error messages as they are appended to the file. Use ^C to break out of tail -f . For example if you didn't set up access to "server-info", you can run

tail /var/log/apache2/error.log

and in the output you should see something similar to

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

indicating that both mod_apreq2 and mod_perl are installed and running.

Installing a Database

This section installs either MySQL or MariaDB as the database manger for webwork. Either works well with WeBWorK.

Installing and Testing MySQL

$ sudo apt install mysql-server libdbd-mysql-perl

This needs to be tested

First check that MySQL is running by

$ sudo mysql
[sudo] password for wwadmin: <wwadmin password>

You should see something very similar to

Welcome to the MySQL monitor.  Commands end with ; or \g.
Your MySQL connection id is 8
Server version: 8.0.20-0ubuntu0.20.04.1 (Ubuntu)
...

Type 'help;' or '\h' for help. Type '\c' to clear the current input statement.

Enter exit to exit

mysql> exit
Bye
$

Installing and Testing MariaDB

Install MariaDB using the distro packages.

$ sudo apt install mariadb-server libdbd-mariadb-perl

Then we should secure the server

$ sudo mysql_secure_installation

[sudo] password for wwadmin: <wwadmin password>

You can setup the VALIDATE PASSWORD plugin if you wish. I chose not to.

Next you will be asked to enter a New password for the MySQL "root" user. Enter your chosen MySQL root 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.

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. Now test that all is well:

$ sudo mysql 
[sudo] password for wwadmin: <wwadmin password>

You should see

Welcome to the MySQL monitor ...
mysql>

Now lets check the MySQL users. There are five accounts. To see the accounts, do the following

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

You will see a table with five users (debian-sys-maint, mysql.infoschema, mysql.session, mysql.sys and root). You should see that one of the five users has a valid password (which will be displayed in encrypted form) and root is authenticated by a socket. You can ignore the mysql.session, mysql.sys and mysql.infoschema users.

Now exit MySQL

mysql> exit
Bye
$

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.

To change the default MySQL engine from InnoDB to MyISAM do the following:

$ cd /etc/mysql/mysql.conf.d
$ sudo cp mysqld.cnf mysqld.cnf.bak1
[sudo] password for wwadmin: <wwadmin password>
$ sudo nano mysqld.cnf

Search for [mysqld] and under "Basic Settings" above the "user = mysql" line add the line

default-storage-engine = myisam

Then save the file and quit. Restart Mysql

$ sudo /etc/init.d/mysql restart
[sudo] password for wwadmin: <wwadmin password>

or

$ sudo service mysql restart
[sudo] password for wwadmin: <wwadmin password>

and log into mysql

$ sudo mysql 
[sudo] password for wwadmin: <wwadmin password>

You will see

Welcome to the MySQL monitor ...
mysql>

If you show MySQL engines

mysql> SHOW ENGINES\G

you should see that MyISAM is listed as the default engine:

...
*************************** 5. row ***************************
      Engine: MyISAM
     Support: DEFAULT
     Comment: MyISAM storage engine 
Transactions: NO
          XA: NO
  Savepoints: NO

Now exit

mysql> exit
Bye
$

Downloading the WeBWorK System Software and Problem Libraries

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 (^C) them from this document and paste (<Shift> <Ctrl> <V> or <Shift> <Insert>) them in a terminal window

$ cd
$ cd downloads
$ git clone git://github.com/openwebwork/webwork2.git
$ git clone git://github.com/openwebwork/pg.git
$ git clone git://github.com/openwebwork/webwork-open-problem-library.git

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.

The first and second download gives you the latest released versions. 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).

The main information page about WebWork downloads is available at http://webwork.maa.org/wiki/Category:Release_Notes

The main information page about the OPL is available at http://webwork.maa.org/wiki/Open_Problem_Library

Installing WeBWorK

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.

Move the System into the Required Directories

As root create a webwork directory under /opt, change the ownership of the webwork directory to www-data, which is what the apache server runs as and move directories there.

$ cd
$ cd downloads
$ sudo mkdir /opt/webwork
[sudo] password for wwadmin: <wwadmin password>
$ sudo chown www-data:www-data /opt/webwork
$ mv webwork2 /opt/webwork/
$ mv pg /opt/webwork/

Now create the courses and libraries directories under webwork and copy and move content there

$ mkdir /opt/webwork/courses
$ mkdir /opt/webwork/libraries
$ mv webwork-open-problem-library /opt/webwork/libraries/
$ cd /opt/webwork/webwork2/courses.dist
$ cp *.lst /opt/webwork/courses/
$ rsync -a modelCourse /opt/webwork/courses/

Setting Permissions

The PG installation directory and files should be owned by www-data and not writable by other users:

$ cd /opt/webwork/pg
$ chmod -R u+rwX,go+rX .

Most WeBWorK directories and files should also be owned by www-data and not writable by other users:

$ cd /opt/webwork/webwork2
$ chmod -R u+rwX,go+rX .

Certain data directories need to be writable by the web server. These are DATA, courses, htdocs/tmp, logs, and tmp. 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 www-data, containing both the WeBWorK administrators and the web server. Consider the user WWADMIN

Run the command:

$ sudo adduser WWADMIN www-data

$ id WWADMIN

and then you should see wwdata listed under groups. Also

$ id www-data

should show www-data listed under groups.

Now we make the WeBWorK directories that need to be writable by the web server have www-data 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.

$ sudo su
[sudo] password for wwadmin: <wwadmin password>
# cd /opt/webwork/webwork2/
# chgrp -R www-data DATA ../courses htdocs/tmp htdocs/applets logs tmp /opt/webwork/pg/lib/chromatic
# chmod -R g+w DATA ../courses htdocs/tmp htdocs/applets logs tmp /opt/webwork/pg/lib/chromatic
# find DATA/ ../courses/ htdocs/tmp logs/ tmp/ -type d -a -exec chmod g+s {} \;
# exit
$

Compile color.c

$ cd /opt/webwork/pg/lib/chromatic
$ gcc color.c -o color

You may see some warning messages which you can safely ignore.

Configuring the Shell

To make working with WeBWorK easier, there are a couple of changes you can make to your shell environment.

Add the WeBWorK bin 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 .bashrc file

$ cd
$ cp .bashrc .bashrc.bak1

Now edit .bashrc

$ nano .bashrc

After the last line add the three lines:

export PATH=$PATH:/opt/webwork/webwork2/bin
export WEBWORK_ROOT=/opt/webwork/webwork2
export PG_ROOT=/opt/webwork/pg

Then save the file and Quit.

Close your Terminal Window and open a new one so the above changes take effect. You can check that they have by

$ echo $PATH
$ echo $WEBWORK_ROOT
$ echo $PG_ROOT

Checking Module Dependencies

WeBWorK includes a script called check_modules.pl (in the directory /opt/webwork/webwork2/bin) 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.

$ check_modules.pl apache2

Scroll up and look through the listing. It should find everything. If something is missing (flagged by **), look back through these instructions to find where it should have been installed and install it.

You may see some warning messages like

Prototype mismatch: sub main::from_json: none vs ($@) at (eval 188) line 2.
Prototype mismatch: sub main::to_json: none vs ($@) at (eval 188) line 2.

This is a known bug in libjson-perl and can be safely ignored.

A common perl package that isn't installed is Statistics::R::IO. It can be installed with

$ cpanm Statistics::R::IO

which will install any needed dependencies and run tests.

Obtaining Javascript Libraries

Javascript libraries are now obtained using npm. This includes the following javascript packages:

codemirror
fontawesome
iframe-resizer
jQuery
jQuery-ui
MathJax
nestedSortable

To install all of these:

$ cd /opt/webwork/webwork2/htdocs/
$ npm install

Checking LaTeX packages

Now we check that all necessary LaTeX packages have been installed. Run the commands

$ cd
$ pdflatex /opt/webwork/webwork2/bin/check_latex.tex

and look for missing packages (you can ignore "No file check_latex.aux.").

Configuring WeBWorK

Making Copies of the Distribution Configuration Files

Before configuring the system, you must make local copies of the site.conf and localOverrides.conf configuration files, located in /opt/webwork/webwork2/conf/ .

$ cd /opt/webwork/webwork2/conf
$ cp site.conf.dist site.conf
$ cp localOverrides.conf.dist localOverrides.conf

System Configuration

Most WeBWorK configuration is done in the files /opt/webwork/webwork2/conf/site.conf and /opt/webwork/webwork2/conf/localOverrides.conf. These files provide system-wide configuration settings, and defaults for course settings. Any setting in these files can be overridden in the course.conf file for a particular course. To override a setting for a course, just put the new setting (using the same syntax as is in localOverrides.conf) in the course.conf file. An instructor can only edit the course.conf file herself (for her own course) if she has "admin" privilege which by default 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.

Actually there are three main configuration files, site.conf, defaults.config and localOverrides.conf. The reason there are three configuration files is to make upgrading WeBWorK easier.

site.conf: This file contains global variables which are required for basic configuration. It will not be overridden when you update WeBWorK but its distribution version, site.conf.dist will be.
defaults.config: This file contains initial settings for many customizable options in WeBWorK. Do not edit defaults.config. It will be overridden next time you upgrade.
localOverrides.conf This is where you should add all local customizations. It will not be overridden when you update WeBWorK but its distribution version, localOverrides.conf.dist will be.

There are several options that must be set for WeBWorK to work with your system. The rest of the file consists of customization options.

Edit the site.conf file

Now edit site.conf

$ cd /opt/webwork/webwork2/conf
$ nano site.conf

First we have to add information about the Apache2 server setup. Search for server_root_url and edit the line so that it reads:

$server_root_url   = 'http://yourserver.yourschool.edu';

where of course you should edit yourserver.yourschool.edu appropriately. The "http://" is important. If you are running a secure server (i.e., using SSL - really TLS), the url should start with https: 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.

Database Settings

Search for the code $database_driver. Uncomment the type of database you set up (MySQL or MariaDB) and comment out the other.

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 <mysql root password> which is the unused password we set when securing MySQL. Search for database_password and replace the line

$database_password = "passwordRW";

by

$database_password = 'database_password';

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.

WeBWorK sends mail in three instances. The PG system sends mail to report answers to questionnaires and free-response problems. The mail merge module is used to send mail to course participants, i.e. to report scores. The feedback module allows participants to send mail to course instructors.

To send mail, WeBWorK needs the address of an SMTP server. Normally you will use the address of your school's SMTP server. If the local machine is running an SMTP server, use localhost. 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 From address on the mail message). Edit the lines

$mail{smtpServer} = ;  # e.g. 'mail.yourschool.edu' or 'localhost'
$mail{smtpSender} = ;  # e.g.  'webwork@yourserver.yourschool.edu'

entering the appropriate information. Be sure to use single quotes and NOT double quotes around email addresses otherwise Perl will treat @ as an array variable.

WeBWorK uses the DateTime module. DateTime is supposed to be able to determine the local timezone itself without you having to enter it but this often fails so it is best to just set it here. For is a list of timezones recognized by DateTime run the command

timedatectl list-timezones

These timezones are more refined than standard time zone usage in that they include switches to daylight savings time (e.g. some parts of a time zone may make the switch and others may not). For example if your server is in the eastern US, on the list you will see America/New_York and you should enter $siteDefaults{timezone} = "America/New_York"; which is the default. Read the documentation in this section of the the site.conf file for more information on selecting time zones and formatting dates.

Search for $siteDefaults{timezone} and enter your local timezone if it is not correct.

Note: Some servers will need to set a value of $server_apache_version in site.conf. 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 ServerTokens Prod 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 Can't locate object method "remote_addr" via package "Apache2::Connection" at /opt/webwork/webwork2/lib/WeBWorK/Authen.pm which will also appear in the Apache error.log file. The fix is to search for $server_apache_version, 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).

Then save the file and Quit.

Default Header Files

After you have used WeBWorK for awhile, you may want to change the default header files in defaults.config. Search for $webworkFiles{screenSnippets}{setHeader} and $webworkFiles{hardcopySnippets}{setHeader} in localOverrides.config. 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 course.conf.

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 %showeditors 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 %showeditors structure to course.conf and then edit it to make available the desired editors.

Set up the webwork database

WeBWorK uses a single database, called webwork, for all courses. We will create the webwork database now.

To do this do the following (before you just copy, paste and hit <Enter> notice that you have to replace database_password with the password you set when editing site.conf above):

$ sudo mysql 
[sudo] password for wwadmin: <wwadmin password>

mysql> CREATE DATABASE webwork;
mysql> CREATE USER 'webworkWrite'@'localhost' IDENTIFIED BY 'database_password';
mysql> GRANT SELECT, INSERT, UPDATE, DELETE, CREATE, ALTER, DROP, LOCK TABLES ON webwork.* TO 'webworkWrite'@'localhost';
mysql> exit
Bye
$

where as we said replace database_password with the password you set when editing site.conf above.

Configuring Apache

WeBWorK ships with an Apache config file that needs to linked into your Apache configuration process. The file is named webwork.apache2.4-config.dist and located in the conf directory. First, copy the file to webwork.apache2-config:

$ cd /opt/webwork/webwork2/conf
$ cp webwork.apache2.4-config.dist webwork.apache2.4-config

and now link it into your Apache configuration process

$ sudo su
[sudo] password for wwadmin: <wwadmin password>
# cd /etc/apache2/conf-enabled
# ln -s /opt/webwork/webwork2/conf/webwork.apache2.4-config webwork.conf

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.

# a2dismod mpm_event
# a2enmod mpm_prefork

Next we will make a few changes to Apache's default configuration. We need to edit two files. First we will save copies of the original files.

# cd /etc/apache2/
# cp apache2.conf apache2.conf.bak1
# cd /etc/apache2/mods-available/
# cp mpm_prefork.conf mpm_prefork.conf.bak1
# exit

Edit apache2.conf

$ cd /etc/apache2/
$ sudo nano apache2.conf

Search for the line

Timeout 300

and replace it by

Timeout 1200

Then save the file and quit.

Edit mpm_prefork.conf

$ cd /etc/apache2/mods-available/
$ sudo nano mpm_prefork.conf

Search for the lines

    MaxRequestWorkers        150
    MaxConnectionsPerChild   0

Which occur under <IfModule mpm_prefork_module> and replace them by

# For WeBWorK a rough rule of thumb is 5 MaxRequestWorkers per 1 GB of memory
      MaxRequestWorkers        10
      MaxConnectionsPerChild   50

where you should set MaxRequestWorkers depending on the amount of memory your server has using the above rule of thumb. Note that for 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.

Then save the file and quit.

Finally we copy WeBWorK's icon file favicon.ico to Apache's www directory.

$ sudo cp /opt/webwork/webwork2/htdocs/favicon.ico /var/www/html
[sudo] password for wwadmin: <wwadmin password>

Now stop and start Apache. We do it this way to make sure the MPM gets changed.

$ sudo apache2ctl stop
[sudo] password for wwadmin: <wwadmin password>
$ sudo apache2ctl start

Test your configuration

Test the /webwork2 location by visiting http://yourserver.yourschool.edu/webwork2. You should see the WeBWorK home page with no courses listed. Actually the directory /opt/webwork/courses/ does contain the modelCourse but the modelCourse 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 /opt/webwork/courses/modelCourse/ contains a file named hide_directory and so the modelCourse is not visible.
Test the /webwork2_files location by visiting http://yourserver.yourschool.edu/webwork2_files. You should see the "WeBWorK Placeholder Page".
You cannot test the /webwork2_course_files location until you have created a course.

If Something is Wrong

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 localOverrides.conf caused me problems, another time it was a missing single quote). A quick way to check this is to do a diff between the edited and distributed versions and check that diff reports the changes you made and only those. Another thing is to look at the Apache error log which is located at /var/log/apache2/error.log.

$ cd /etc/apache2/
$ diff apache2.conf apache2.conf.bak1
$ cd /opt/webwork/webwork2/conf/
$ diff site.conf site.conf.dist
$ diff localOverrides.conf localOverrides.conf.dist
$ diff webwork.apache2.4-config webwork.apache2.4-config.dist
$ tail /var/log/apache2/error.log

If something is wrong and you fix it, you will have to restart Apache for the changes to take effect

$ sudo service apache2 restart
[sudo] password for wwadmin: <wwadmin password>

Create the admin Course

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

$ cd /opt/webwork/courses
$ /opt/webwork/webwork2/bin/addcourse admin --db-layout=sql_single --users=adminClasslist.lst --professors=admin
$ sudo chown -R www-data:www-data  admin 
[sudo] password for wwadmin: <wwadmin password>

where the last line makes the course admin and its subdirectories owned by the Apache server and readable/writeable by the WWADMIN user.

Now goto http://yourserver.yourschool.edu/webwork2 and should see the WeBWorK home page with Course Administration listed at the top. Click on it and login with Username admin and Password admin . This first thing you should do is register your new WeBWorK installation. It's quick and easy, just click on Register. IMPORTANT The next thing you should do is click on User Settings and change admin 's password to something more secure than admin .

Unless you choose otherwise, users with admin privileges in the admin course (i.e. WeBWorK administrators) will automatically be added to new courses with admin privileges and the same password as in the admin course. Initially the only such user is admin (hopefully you are not confused by the fact that the course admin has a user named admin). It's usually convenient make yourself a WeBWorK administrator. To do this (assuming you are logged in as admin to the admin course at http://yourserver.yourschool.edu/webwork2/admin )

Click on Classlist Editor in the left panel
Click the Add tag and click Take Action!
Enter the appropriate information (you can use your Login Name as the Student ID if you want and also you can leave the last three items blank) and click Add Students
Click on Classlist Editor in the left panel again
When you enter a new student, by default their Student ID is used as their password. We'll change this now.
Select yourself with a check mark and click the Password tag and click Take Action!. (Note as a safely mechanism you can not change the password for the user you are logged in as, currently admin, this way)
Enter the password and then click Take Action!
Finally give yourself admin privileges by selecting yourself with a check mark, clicking the Edit tag and then clicking Take Action! (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)
Now at the far right change Permission Level from student to admin
Then click Take Action!

At some point you will probably want to hide the admin course so that it is not listed on the WeBWorK home page. As we noted above the modelCourse, 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 modelCourse is very useful as a model (hence its name) for setting up other courses. The admin course is used for administering WeBWorK and even though regular users can not log into it (you did change the admin password, didn't you!!), it a little bit cleaner and safer to hide it from prying eyes. To hide (or unhide) a course select Hide Inactive courses 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 admin course using the URL http://yourserver.yourschool.edu/webwork2/admin but you will not see a link for it on the WeBWorK home page http://yourserver.yourschool.edu/webwork2 .

Now goto http://yourserver.yourschool.edu/webwork2 and no course will be listed.

Checking for and Installing Hotfixes

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

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

Updating the webwork2 code

First we check for updates to the webwork2 code:

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

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

git pull origin and restart apache2.

Updating the pg code

Now check for updates to the pg code:

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

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

git pull origin

and restart apache2.

Restart apache2

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

$ sudo apache2ctl restart
password:<wwadmin password>

Updating the OPL

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

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

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

git pull origin

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

$ OPL-update

Starting and Stopping Apache and MySQL

If you make changes to the system, you will have to restart apache2 before the changes take effect. On rare occasions you may need to restart MySQL.

Starting and Stopping Apache

You have to run these commands as root.

To start or restart (i.e. stop and then start) the apache2 webserver run the command

$ sudo apache2ctl graceful
[sudo] password for wwadmin: <wwadmin password>

You can also start apache2 by

$ sudo apache2ctl start
[sudo] password for wwadmin: <wwadmin password>

and restart it with

$ sudo apache2ctl restart
[sudo] password for wwadmin: <wwadmin password>

restart is less graceful but more powerful than graceful. Sometimes graceful fails to kill all apache2 child processes.

To stop the Apache webserver run the command

$ sudo apache2ctl stop
[sudo] password for wwadmin: <wwadmin password>

Stopping and then starting Apache should definitely kill all apache2 child processes.

You can also start or stop apache2 by using the init.d script apache2. Run

$ sudo /etc/init.d/apache2
[sudo] password for wwadmin: <wwadmin password>

or equivalently

$ sudo service apache2
[sudo] password for wwadmin: <wwadmin password>

and you will get a list of allowed commands (start, stop, restart, etc.).

Finally you can use the newer systemctl method, e.g.

sudo systemctl start apache2
[sudo] password for wwadmin: <wwadmin password>

sudo systemctl --help

will give you a list of all possible commands, the main ones being start, stop, restart and status.

Starting and Stopping MySQL

You have to run these commands as root.

To start the MySQL server run the command

$ /etc/init.d/mysql start

To stop the MySQL server run the command

$ sudo /etc/init.d/mysql stop

To restart the MySQL server run the command

$ sudo /etc/init.d/mysql restart

Equivalently you can use the command

$ systemctl start mysql

and start can be replaced by stop and restart. Also,

$ systemctl status mysql

gives information about the mysql server.

$ systemctl --help

will give you a list of all possible commands.

Starting and Stopping MariaDB

You have to run these commands as root.

To start the MariaDB server run the command

$ /etc/init.d/mysql start

To stop the MariaDB server run the command

$ sudo /etc/init.d/mysql stop

To restart the MariaDB server run the command

$ sudo /etc/init.d/mysql restart

Equivalently you can use the command

$ systemctl start mariadb

and start can be replaced by stop and restart. Also,

$ systemctl status mariadb

gives information about the mysql server.

$ systemctl --help

will give you a list of all possible commands.

Install the WeBWorK Problem Libraries

Before we create a real course we will install the WeBWorK Problem Libraries.

Install the Open Problem Library

The Open Problem Library 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.

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.

$ cd /opt/webwork/courses/modelCourse/templates/
$ ln -s /opt/webwork/libraries/webwork-open-problem-library/OpenProblemLibrary Library

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, 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 below), you may see errors when viewing problems (you definitely will see errors in the Orientation set).

Next we have to run the OPL-update script which will create the data that the Library Browser uses.

$ OPL-update

This has to convert a lot of data for over 37,000 problems so please be patient; it can take a long time.

If at some time in the future you want to upgrade the Problem Library, the process is easy, see Updating the OPL. Note that this is something you should do fairly often so that your library is up to date with new problems and bug fixes for old ones.

Initialize the OPL local statistics database table

Run the command

$ update-OPL-statistics.pl

to create a table to hold the OPL local statistics. See https://webwork.maa.org/wiki/OPL_Problem_Statistics for information.

If this table does not exist, when you try to view problems in the Library Browser, you will see the following error message:

"couldn't find the opl local statistics table"

This should really be run automatically by the OPL-update script above but unfortunately the current version of that script has a typo,

do $ENV{WEBWORK_ROOT}.'/bin/update-OPL-statistics';

whereas the line should really be

do $ENV{WEBWORK_ROOT}.'/bin/update-OPL-statistics.pl';

Set up the access to the Contrib directory

The Contrib 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 Contrib 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 Contrib directory.

Put a link to the Contrib directory in the modelCourse so that when we create courses copying templates from the modelCourse, the Contrib directory will be available.

$ cd /opt/webwork/courses/modelCourse/templates/
$ ln -s /opt/webwork/libraries/webwork-open-problem-library/Contrib Contrib

If you just want to do this for individual courses, not all courses then don't put the link in the modelCourse above, and then do the following. Note we don't have any individual courses yet. But for example after creating myTestCourse below, to set up access to the Contrib directory from myTestCourse, do the following

$ cd /opt/webwork/courses/myTestCourse/templates/
$ sudo $ ln -s /opt/webwork/libraries/webwork-open-problem-library/Contrib Contrib
[sudo] password for wwadmin: <wwadmin password>

Set up the Rochester and Union Libraries

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 OPL Directory button.

First we need to edit localOverrides.conf one last time

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

Search for courseFiles{problibs} and scroll down several lines to the lines

#       rochesterLibrary => "Rochester",
# 	unionLibrary     => "Union",

Uncomment these lines (i.e. remove the #) so they become

      rochesterLibrary => "Rochester",
      unionLibrary     => "Union",

Then save the file and quit.

We next put links to the Rochester and Union Libraries in the modelCourse so that when we create courses copying templates from the modelCourse, 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 OPL Directory 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.

$ cd /opt/webwork/courses/modelCourse/templates/
$ ln -s /opt/webwork/libraries/webwork-open-problem-library/OpenProblemLibrary/Union unionLibrary
$ ln -s /opt/webwork/libraries/webwork-open-problem-library/OpenProblemLibrary/Rochester rochesterLibrary

If you want to put another library into the modelCourse, just do the analogous thing. If you just want the additional library in a particular course, add the link in the templates directory of that course. If you look in the directory /opt/webwork/libraries/webwork-open-problem-library/OpenProblemLibrary/ you might find other libraries that are not yet listed in global.conf and these can be added in the same way as the Rochester and Union libraries. Finally if you add a library with non standard symbols in the name (e.g. uva-statLibrary) you have to use single quotes when adding it to global.conf, e.g.
'uva-statLibrary' => "UVA-Stat",
It's easier to just avoid such names.

Install and Set Up the CAPA Library

This step is optional. It installs and sets up the CAPA Library, which is a library of physics problems.

Note: We are in the process of integrating the CAPA problems into the main distribution so some of the details below may change.

Move the CAPA graphics files to the required locations and set the group.

$ cd /opt/webwork/libraries/webwork-open-problem-library/Contrib/CAPA                                                                        
$ mv CAPA_Graphics /opt/webwork/webwork2/htdocs/
$ sudo chgrp -R wwdata /opt/webwork/webwork2/htdocs/CAPA_Graphics
  [sudo] password for wwadmin: <wwadmin password>
$ sudo chmod -R g+w /opt/webwork/webwork2/htdocs/CAPA_Graphics

We need to edit localOverrides.conf again

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

Now search for the lines

$pg{specialPGEnvironmentVars}{CAPA_Tools}             = "$courseDirs{templates}/Contrib/CAPA/macros/CAPA_Tools/",
$pg{specialPGEnvironmentVars}{CAPA_MCTools}           = "$courseDirs{templates}/Contrib/CAPA/macros/CAPA_MCTools/",
$pg{specialPGEnvironmentVars}{CAPA_GraphicsDirectory} = "$courseDirs{templates}/Contrib/CAPA/CAPA_Graphics/",
push @{$pg{directories}{macrosPath}},
  "$courseDirs{templates}/Contrib/CAPA/macros/CAPA_Tools",
  "$courseDirs{templates}/Contrib/CAPA/macros/CAPA_MCTools";

and replace these six lines by

################################################################################
#Locations of CAPA resources. (Only necessary if you need to use converted CAPA problems.)
################################################################################
$pg{specialPGEnvironmentVars}{CAPA_Tools}             = "$courseDirs{templates}/Contrib/CAPA/macros/CAPA_Tools/",
$pg{specialPGEnvironmentVars}{CAPA_MCTools}           = "$courseDirs{templates}/Contrib/CAPA/macros/CAPA_MCTools/",
$pg{specialPGEnvironmentVars}{CAPA_GraphicsDirectory} = "$webworkDirs{htdocs}/CAPA_Graphics/";
$pg{specialPGEnvironmentVars}{CAPA_Graphics_URL}      = "$webworkURLs{htdocs}/CAPA_Graphics/";

Then save the file and Quit.

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

$ cd /opt/webwork/courses/modelCourse/templates/
$ ln -s /opt/webwork/libraries/webwork-open-problem-library/Contrib/CAPA/   capaLibrary

More likely if you just want to do this for individual courses, not all courses then don't put the link in the modelCourse above, and then do the following. We don't have any yet. But for example after creating myTestCourse below, to set up access to the CAPA Library from myTestCourse, do the following

$ cd /opt/webwork/courses/myTestCourse/templates/
$ sudo ln -s /opt/webwork/libraries/webwork-open-problem-library/Contrib/CAPA/   capaLibrary
[sudo] password for wwadmin: <wwadmin password>

and do the analogous thing for every course that needs access to the CAPA Library. Then to gain access to the CAPA Library from the course, simply go to the Library Browser and click on the CAPA button.

Installation Manual for 2.16 on Ubuntu

Contents

Notation

Install Software Packages

Ubuntu Software Packages

Installation of Other Perl Modules with cpanm

Apache2 Modules and mod perl

enabling info.conf and status.conf in Ubuntu

Fully Qualified Domain Name

Test Apache

Installing a Database

Installing and Testing MySQL

Installing and Testing MariaDB

Downloading the WeBWorK System Software and Problem Libraries

Installing WeBWorK

Move the System into the Required Directories

Setting Permissions

Compile color.c

Configuring the Shell

Checking Module Dependencies

Obtaining Javascript Libraries

Checking LaTeX packages

Configuring WeBWorK

Making Copies of the Distribution Configuration Files

System Configuration

Edit the site.conf file

Database Settings

Default Header Files

Set up the webwork database

Configuring Apache

Edit apache2.conf

Edit mpm_prefork.conf

Test your configuration

If Something is Wrong

Create the admin Course

Checking for and Installing Hotfixes

Updating the webwork2 code

Updating the pg code

Restart apache2

Updating the OPL

Starting and Stopping Apache and MySQL

Starting and Stopping Apache

Starting and Stopping MySQL

Starting and Stopping MariaDB

Install the WeBWorK Problem Libraries

Install the Open Problem Library

Initialize the OPL local statistics database table

Set up the access to the Contrib directory

Set up the Rochester and Union Libraries

Install and Set Up the CAPA Library

Navigation menu

Search