Installation Manual for 2.7 on Ubuntu 12.04

This article has been retained as a historical document. It is not up-to-date and the formatting may be lacking. Use the information herein with caution.

These instructions cover the installation of the Ubuntu Linux 12.04 LTS operating system and WeBWorK 2.7 from scratch. Note that you can also quickly install Ubuntu 12.04 and WeBWorK 2.7 from the WeBWorK Live DVD (see Installing_from_WW2.7_Ubuntu12.04_Vanilla_LiveDVD) or, if you want to run WeBWorK on a virtual machine, from the WeBWorK Virtual Machine Image (see Installing_from_WW2.7_Ubuntu12.04_Vanilla_Virtual_Machine_Image).

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

These instructions are more detailed (but offer fewer choices and often less background information) than the general Installation Manual for 2.4 and are aimed at non unix experts. Readers may want to quickly scan Installation Manual for 2.4 to get an overview of the installation process and then carefully read and follow these instructions.

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. <root password> to indicate you have to enter the root 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.

Installing the Ubuntu 12.04 Linux Operating System

Installation CD

Obtain the Desktop Edition installation DVD/CD set. Connect to http://www.ubuntu.com/ for information. For example you can download an ISO image of the installation CD and then burn your own installation CD. You want the file ubuntu-12.04-desktop-amd64.iso or, if you have a very old server, ubuntu-12.04-desktop-i386.iso. Choose the former to take full advantage of computers based on the AMD64 or EM64T architecture (e.g., Athlon64, Opteron, EM64T Xeon, Core 2). Note 1: We recommend you use the "Long Term Support" (LTS) version of Ubuntu which is currently version 12.04; the next LTS release will be version 14.04. Note 2: We recommend you actually use the latest 12.04 iso file which is currently ubuntu-12.04.2-desktop-amd64.iso. Choose which ever download site works best for you; I have had good luck with http://mirrors.kernel.org/ubuntu-releases/ If you download the ISO image, make sure that you verify the integrity of the downloaded file by comparing the MD5 checksum of the downloaded file with the MD5 checksum listed at https://help.ubuntu.com/community/UbuntuHashes or at the download site (e.g. http://mirrors.kernel.org/ubuntu-releases/12.04/MD5SUMS). These instructions will assume you have the ubuntu-12.04.4-desktop-amd64.iso installation CD but installing from the i386, alternate CD, a commercial DVD/CD set or from the net should be essentially identical.

You will want to have you computer connected by ethernet to the internet for the installation. Place the installation CD in your DVD/CD drive and reboot your computer from the DVD drive. You may have to press a key (e.g. <F12>) during the boot process to bring up a boot menu which will allow you to select booting from the DVD. Or you many have to edit the BIOS to select the DVD as the first boot device. See https://help.ubuntu.com/community/BootFromCD for help.

After the system boots you will be presented with a series of 7 steps.

Step 1

On the first install panel keep English as the selected language and click Install Ubuntu, the second (to the right) option.

Step 2

Just hit Continue on the next page

Optional Configurations

If you will have a large number of users (say over a 1,000) and/or a slow server, you may want to consider the first two optimizations. They are independent but related and deal with how WeBWorK handles various temporary and static files. We call these two options Optional A and Optional B. The third option, Optional C, gives greater security.

Optional A creates a separate partition (or directory) on which are stored all of WeBWorK's "temporary" files. 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 you do so.

Optional B installs and configures a lightweight webserver. Apache is a very standard and powerful webserver which we use to serve WeBWorK pages. However its child processes use a lot of resources (e.g. memory). When serving static files and images, a much lighter weight webserver can be used. This can substantially reduce the load on a heavily used server.

Optional C configures Apache so that access to WeBWorK will be through an encrypted Secure Sockets Layer (SSL) with an https: URL.

Except for creating a separate partition, we will wait until WeBWorK is installed and tested before implementing these options. We mention them here because the next step is partitioning the disks.

Partition disks

Step 3 (Note to Pizer --- Update this)

Next comes the Partition disks pages. You should be able to accept the defaults unless you want to follow Optional A and/or create separate partitions for various directories. There is a lot of information on the web if you don't want to accept the default partition set up. If you want to implement Optional A follow the directions below. Note that if you only want to implement Optional A with a separate directory, not a separate partition, you don't have to do anything special with partitions at this point. At the bottom of this page you have options on installing the boot loader but you almost certainly want to use the defaults.

Optional A: The default partitioning scheme creates just two partitions, a root (/) partition and a swap partition. Here we will create those and an additional partition for WeBWorK's temporary files.

1. On the Partition disks page use <Tab> to select Go Back and then select Partition disks
2. Use the down arrow to select your disk (sda)
3. On the You have selected an entire device to partition... page select Yes to the question Create new empty partition table on this device
4. On the This is an overview... page select FREE SPACE
5. On the How to use this free space page select Create a new partition
6. Now you have to decide how to allocate your disk space. The rule of thumb is to use twice the amount of RAM you have for swap (e.g. 2 GB if you have 1 GB of RAM). For WeBWorK's temporary files 25 GB for every 1,000 students should be ample. You can allocate the remainder of your disk space to the root (/) partition. Actually if you are going through the trouble of doing this, you probably will want to research other partitioning recommendations.
7. On the The maximum size you can use... page enter the size for your root (/) partition and Continue
8. Select Primary for the type of the new partition
9. Select Beginning for the location of the new partition
10. Select / for the Mount point of the new partition and then select Done setting up the partition

Now we repeat the process for the partition which will hold WeBWorK's temporary files.

1. On the This is an overview... page select FREE SPACE
2. On the How to use this free space page select Create a new partition
3. On the The maximum size you can use... page enter the size for WeBWorK's temporary files partition. As we said 25 GB for every 1,000 students should be ample. Then Continue
4. Select Logical for the type of the new partition
5. Select Beginning for the location of the new partition
6. Select Mount point and then hit <Enter>
7. Select Enter manually and then hit <Enter>
8. For the Mount point for this partition enter /var/www/wwtmp and Continue
9. Then select Done setting up the partition

Finally we set up the swap partition

1. On the This is an overview... page select FREE SPACE
2. On the How to use this free space page select Create a new partition
3. On the The maximum size you can use... page enter the size for swap partition. As we said the rule of thumb is to use twice the amount of RAM you have. Then Continue
4. Select Logical for the type of the new partition
5. Select Beginning for the location of the new partition
6. Select Use as and then hit <Enter>
7. Select swap area and then hit <Enter>
8. Then select Done setting up the partition

Finally

1. Review your changes and
2. Select Finish partitioning and write changes to disk and then hit <Enter>
3. Select Yes to confirm the changes

Continue Initial Installaion

Step 3

Select the partition you want to install Ubuntu in and hit Continue (Note to Pizer: test this on a empty disk. It presents multiple choices if the disk already has installed OS's)

Step 4

Select a city in your time zone and hit Continue

Step 5

Hit Continue to accept the default keyboard layout

Step 6

The next panel asks "Who are you?". What you fill in here is a privileged user so you might want to enter a special administrative account rather than your normal account. We suggest <wwadmin> but you can use whatever you want.

• Enter the information for "Your name"
• Enter the information for "Your Computer's name"
• Enter the information for "Pick a username" In these instructions, we will call this name <wwadmin>.
• Enter the information twice for the password. In these instructions, we will call this password the <wwadmin password>.

• Then hit Continue to continue

Step 7

Chose a picture. I just hit Continue

Step 8

If the page about importing accounts appears just hit Continue to continue without importing anything

Now sit back and relax while the installation takes place. Some of the steps can take a long time. Please be patient. When you finally see "Installation complete" hit Restart now.

Continue Installation

After this finishes the system will ask you to reboot and eject the CD after you do.

1. Log into your account
2. At some point the Update Manager icon may appear. If it does, open it and accept all updates. Alternately you can open Dash Home, type Update and open the Update Manager. Click Install Updates. You may have to enter the <wwadmin password> which functions as the <root password> and click Authenticate. Follow any instructions, e.g. you may be told to reboot as soon as the installation is completed (to reboot, click on the power button icon in the upper right hand corner, then select Restart)

Test Browser, Network and Keyboard

After reboot and login, click the Firefox icon at the left of the screen and you should be connected to the world. Go to http://webwork.maa.org/wiki/Installation_Manual_for_2.7_on_Ubuntu_12.04 where you can view this document and, if you want, copy commands that you need (see below).

If something is wrong and you are not connected to the web, the first thing to do is check the network information. (Note to Pizer --- Update this)

1. Select System Settings, Network, Wired, Options
2. Select IPv4 Settings
3. Next to Method: and scroll down and select Manual.
4. Click Add and then enter your servers IP address, Netmask (usually 255.255.255.0 but possibly 255.255.0.0) and Gateway address (often the same as the IP address with the last number replaced by 1). Important: After entering a number hit the <Enter> key so that the change is recorded.
5. Next enter the IP address(es) of your DNS server(s)separated by spaces. You need to enter at least one DNS server
6. Finally enter the search domain Hosts
7. Click Save
8. Enter <wwadmin password> and click Authenticate
9. Click Close

Your network connection should start up almost immediately. If you are still having problems first try rebooting (click on the power button button icon in the upper right hand corner, then select Restart)and if that doesn't work it's time to investigate further or seek help.

Here's an aside on keystroke delay and repetition rate. If you are like me and find the keystroke delay too short (so that you often type "geeet" when you want to type "get"), do the following. Select System Settings, Keyboard and then increase the delay time interval and close the window.

Terminal Window Notation and Use

Before installing and configuring additional software, we need to talk about terminal windows.

To open a terminal window select Dash Home and type Terminal. The next time you select Dash Home, the terminal icon might be displayed. Or you can just type <Ctrl> <Alt> <T>.

In a terminal window some commands will have to be run as root whereas others should be run as a regular user. We will use # to indicate that the command is to be run as root e.g.

# perl -MCPAN -e shell

and $ to indicate that the command is to be run as a normal user e.g.

$ cp .bashrc .bashrc.bak1

To execute the above commands you have to hit <Enter>. We'll just assume this. After executing a command, often the system will respond with text (sometimes a lot of text!) which we will usually not repeat below. We only give the commands that you should execute.

The bash shell which you will be using has a number of very convenient features.

One is command and file name completion. If you are typing (e.g. ch) and hit <tab> bash will complete the command or filename if it is unambiguous (or more precisely it will complete as much as possible). If there are multiple possibilities (as in the case of ch) nothing will happen (except you may hear a beep) and you can type more letter(s) and hit <tab> again. Or you can hit <tab> a second time and you will see a list of all possible completions. E.g. entering ch<tab><tab> gives a list of possible completions and ch<tab>gr<tab> (or chgr<tab>) gives chgrp, the change group command. This is very fast and convenient and it also leads to fewer typing errors.

Another useful shortcut is the command history. Using the up and down arrow keys will bring up previous commands which can be edited and then executed. If you are repeating a command or entering a command which is similar to a previous one, this is very useful.

You can copy commands from these instructions (with copy from the Edit dropdown list or ^C) and paste them into a terminal window (with paste from the Edit dropdown list or <Shift> <Ctrl> <V>. Note that <Shift> <Insert> also works). This is an excellent way to use these instructions since it is fast and insures commands are entered correctly (just be careful to read before you run the command and replace things like database_password with the correct code in the few places such things occur).

By default Ubuntu has no password set for the root user. To gain root access you have to use the sudo command with the <wwadmin password>. This is the password you set for the first user (which we called the WeBWorK administrator <wwadmin> while installing Ubuntu. However we will manually set a password for the root user since this is a much more standard setup. To do this, type in the following in a terminal window:

$ sudo passwd
Password: <wwadmin password>

After that you are asked to type in the new root password twice. Enter the password for the root user and Do not forget what you enter here.

Enter new UNIX password: <root password>
Retype new UNIX password: <root password>
passwd: Password updated successfully
$

To test this

$ su
Password: <root password>
# whoami
root
# exit
$

Finally perhaps a safer way to run commands as root is to use the sudo command

$ sudo <command>
Password: <wwadmin password>

After you enter the password the command is executed. For a certain period (maybe 5 minutes) you can execute additional sudo commands without reentering <wwadmin password>. A log of all sudo commands is kept in /var/log/auth.log . In these instructions for the most part we will not use sudo, but keep it in mind for other times that you have to become root in order to execute a few commands (e.g. restarting Apache).

Note that for certain GUI tools such as the Synaptic Package Manager that require root access, the password required is <wwadmin password>, the password for the first account you set up, not the new <root password>.

For our next terminal window task create a downloads directory where we will keep copies of downloaded software.

$ cd
$ mkdir downloads

Ubuntu Software Packages

Our next task is to install a number of Ubuntu software packages. For a very fast way to do this, copy the command at the end of this section, paste it into a terminal window and run it as root. Or you can go through the step by step process using the Synaptic Package Manager as follows.

First of all most Debian based Linux distributions rely on a program called Synaptic Package Manager to install software. However, as of Ubuntu 11.10, Synaptic has been removed from Ubuntu in favor of the Ubuntu Software Center. You can use the Ubuntu Software Center if you wish but I'll give instructions for using Synaptic Package Manager. Note that what I really do is use the very fast way noted above.

First we have to install the Synaptic Package Manager

$ sudo apt-get install synaptic
Password: <wwadmin password>

Just hit <Enter> to accept the defaults. After the installation is complete

1. Select Dash Home and type Synaptic and click on the Synaptic Package Manager icon. You will have to enter the <wwadmin password>. The Synaptic Package Manager window will open
2. Click on Reload to bring the package information up to date

Now we will actually select and install a large number of packages. The process is the same for all packages. I'll give an example of installing libnet-ldap-perl and then just give the list of required packages.

1. Select Search
2. Under Look in: select Name. The default Description and Name sometimes returns too many possibilities
3. We are searching for libnet-ldap-perl so enter ldap-perl (or something similar; you can copy and paste from this document if you want) and click on Search
4. This should result in 6 possibilities. Select and Mark for Installation (by double clicking or checking and then selecting Mark for Installation) libnet-ldap-perl. You will see a pop up window Mark additional required changes? and you should always click Mark to accept the requirements.
5. Follow this basic procedure for all the packages listed below

Here is the list of Ubuntu packages that need to be installed. See Installation Manual for 2.4 for a short explanation of what most of these packages do.

1. apache2
2. apache2-mpm-prefork
3. dvipng
4. gcc
5. git
6. libapache2-request-perl
7. libdatetime-perl
8. libdbd-mysql-perl
9. libemail-address-perl
10. libexception-class-perl
11. libextutils-xsbuilder-perl
12. libfile-find-rule-perl
13. libgd-gd2-perl
14. libhtml-scrubber-perl
15. libjson-perl
16. liblocale-maketext-lexicon-perl
17. libmail-sender-perl
18. libmime-perl
19. libnet-ip-perl
20. libnet-ldap-perl
21. libnet-oauth-perl
22. libossp-uuid-perl
23. libpadwalker-perl
24. libphp-serialization-perl
25. libsoap-lite-perl
26. libsql-abstract-perl
27. libstring-shellquote-perl
28. libtext-csv-perl
29. libtimedate-perl
30. libuuid-tiny-perl
31. libxml-parser-perl
32. libxml-writer-perl
33. make
34. mysql-server
35. netpbm
36. openssh-server
37. preview-latex-style
38. texlive
39. unzip

When I do this I see on the bottom of Synaptic Package Manager window 82 to install/upgrade, 1 to remove. Your numbers may differ slightly. Now click Apply and Apply again to confirm the changes. You will be asked to enter a New password for the MySQL "root" user. Enter your choosen MySQL root password. As was said above, Do not forget what you enter here. Also remember that this is the password for the MySQL root user, not the Ubuntu linux system root user. Below we refer to this as <mysql root password>

That completes the set up of your base Ubuntu system. You can quit the Synaptic Package Manager.

If you would prefer to install all of these packages in one fell swoop, run the following command as root ( $ su <Enter> ; Password: <root password> ):

# apt-get install apache2 apache2-mpm-prefork dvipng gcc git \
libapache2-request-perl libdatetime-perl libdbd-mysql-perl libemail-address-perl \
libexception-class-perl libextutils-xsbuilder-perl libfile-find-rule-perl libgd-gd2-perl \
libhtml-scrubber-perl libjson-perl liblocale-maketext-lexicon-perl \
libmail-sender-perl libmime-perl libnet-ip-perl libnet-ldap-perl libnet-oauth-perl \
libossp-uuid-perl libpadwalker-perl libphp-serialization-perl libsoap-lite-perl \
libsql-abstract-perl libstring-shellquote-perl libtext-csv-perl libtimedate-perl \
libuuid-tiny-perl libxml-parser-perl libxml-writer-perl make mysql-server netpbm \
openssh-server preview-latex-style texlive unzip

When prompted, you can always accept the default (hit <Enter>) except when asked for the password for the MySQL "root" user. In case you skipped by it, look above for information on the New password for the MySQL "root" user. When the process finishes, enter

# exit

to return to a regular user.

Accessing Your Server Remotely

At this point you can login your server from a remote location using SSH (non secure telnet and FTP are not allowed but secure SSH and SFTP are). If you are using "SSH Secure Shell" (now called "SSH Tectia"), a popular SSH client for PC's, you will have to add Keyboard Interactive to the list of "Authentication methods" under "Authentication" if it's not already there.

You can do almost all (all if you are a unix expert) of the remaining installation from a remote location if you wish.

Installing Perl Modules

We now have to install several additional Perl modules which unfortunately are not available from the Debian package system.

Testing Perl Modules

To test if a Perl module is installed and working on your system, issue the following command, replacing Module with the name of the module:

$ perl -MModule -e 'print "installed!\n"'

If the module is installed you will see installed!. If not you will see at lot of gibberish. E.g. at this stage in our installation process CPAN is installed and MXML::Parser::EasyTree is not so

$ perl -MCPAN -e 'print "installed!\n"'

yields

installed!

and

$ perl -MXML::Parser::EasyTree -e 'print "installed!\n"'

yields

Can't locate XML/Parser/EasyTree.pm in @INC (@INC contains: 
/etc/perl ...

You can check the version of an installed module by the following command, replacing Module with the name of the module:

 perl -MModule -e 'print "$Module::VERSION\n"'

For example for the GD.pm module

 perl -MGD -e 'print "$GD::VERSION\n"'

Installing Additional Perl Modules from CPAN

Be aware that in rare cases you might have to as root run

$ su
<root password>
# unset LANG
# exit
$

since otherwise the installation of some modules (Module::Build is an example) may fail.

First we will set up CPAN. For this you have to be root.

$ su
<root password>
# perl -MCPAN -e shell

Since this is the first time you are using CPAN it will ask you Would you like me to configure as much as possible automatically? Answer Yes (the default) and that should be it. If you are asked for a method to use, choose sudo. If you are asked choose some CPAN mirror sites, you can just answer Yes (the default).

Now we update CPAN itself

cpan> install Bundle::CPAN

and always hit <Enter> to accept the defaults when prompted. This can be a long process, please be patient. When you again see the

cpan>

prompt enter

cpan> reload cpan
cpan> o conf commit

Now install the following modules

cpan> install XML::Parser::EasyTree Iterator Iterator::Util Pod::WSDL

and in case you are prompted accept all defaults by just hitting <Enter>. Note that with more than one module to install, we just list them after install separated by spaces.

When you again see the

cpan>

prompt enter

cpan> exit
#

Installing Additional Perl Modules from Source

At one point in time (August 2006), the installation of DateTime using CPAN was broken. Currently DateTime can be installed using CPAN. However it is useful to show you how to install perl modules from source in case one of the perl modules we installed above gets updated and its installation from CPAN becomes broken. If that happens you can follow the procedures outlined here to install the module from source.

IMPORTANT: With Ububtu we have already installed DateTime so you don't have to install it as outlined below. We are just using this as an example of installing a module from source which hopefully you will never have to do. You can skip this section and go directly to the Apache 2 and mod_perl section.

Now we give the example of installing DateTime from source. As we said you can skip this part.

Goto http://search.cpan.org/, search for DateTime and click on DateTime. Then near the top right download DateTime-0.36.tar.gz and save it to disk. Move it to your downloads directory. Then

$ cd 
$ cd downloads
$ tar -zvxf DateTime-0.36.tar.gz
$ cd DateTime-0.36/


$ perl Makefile.PL
$ make
$ make test

If make test indicates something is missing you will have to install that. In fact in the case of DateTime, you would see that quite a few things are missing.

DateTime requires the additional modules version , Module::Build , Class::Singleton , DateTime::TimeZone and DateTime::Locale . We could install these using CPAN

# perl -MCPAN -e shell
cpan> install version Module::Build Class::Singleton DateTime::TimeZone DateTime::Locale
cpan> exit
# exit
$

If you see anything that looks suspicious during this process, you can always test to see if the perl module in question was in fact installed. If it was not installed try CPAN first and if CPAN fails then install it from source. The great thing about CPAN (if it works) is that it will trace down and automatically install all required components. Note that if you get a message indicating that package/file.pm was not found, you should serach for and install package::file since perl modules use a double colon (::) as a directory separator.

Assuming all is OK

$su
<root password>
# make install
# exit
$

Finally you should definitely test that the module (e.g. DateTime) was installed sucessfully

$ perl -MDateTime -e 'print "installed!\n"'

If you see

installed!

you can celebrate.

Apache 2 and mod_perl

First we have to enable a couple Apache modules. Acting as root in a terminal window enter

# a2enmod apreq
# a2enmod info

Next we make a copy of the configuration files 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 gedit. Note that you have to be root to edit these files. First we edit info.conf

$ cd /etc/apache2/mods-available
$ sudo gedit info.conf
Password: <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)

#    Allow from 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 (Save and File, Quit).

Now we edit status.conf

$ cd /etc/apache2/mods-available
$ sudo gedit status.conf
Password: <wwadmin password>

After the comments at the top and above the <Location /server-status> line enter

ExtendedStatus On

Now edit the

#    Allow from 192.0.2.0/24

line just as you did for info.conf. Then save the file and quit.

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.

NOTE TO PIZER: Update this

First we have to install the network manager since it is no longer installed by default in Ubuntu. You can use the Synaptic Package Manager to install gnome-network-admin but the quickest way is to run the command

$sudo apt-get install gnome-network-admin
<wwadmin password>

After this is installed

1. To open the network manager select Dash Home and type Network.
2. Click on Network (not the one with the folder icon)
3. Click unlock
4. Enter <wwadmin password> and click Authenticate
5. Click on General
6. Under Host name enter your_server_name (if it's not already there)
7. Then under Domain name enter your server's domain name, something like department.school.edu

Next

1. Click on Hosts
2. There should also be an entry with your server's IP address (if not you should add one)
3. Select the entry with your server's IP address and click Properties (NOTE: with 9.04 clicking Properties closed the window. In order to edit an entry I first had to delete and then add it back as a new entry. So here and below you may have to use that method to for editing)
4. Under Aliases you should see your server's fully qualified domain name, something like your_server_name.department.school.edu
5. Add or edit these entries if they are not correct
6. Then click OK
7. And click Close to close Network settings

You can check these settings by running the commands

$ hostname --fqdn

and

$ hostname

The first respond with the fully qualified domain name and the second with just your_server_name.

If the command hostname --fqdn returns Unknown host do the following:

1. Select System, Administration, Network
2. Click on Click to make changes
3. Enter <wwadmin password> and click Authenticate
4. Click on Hosts
5. Select the entry with your server's IP address and click Properties
6. Under Aliases you should see your server's fully qualified domain name, something like your_server_name.department.school.edu
7. Select the entry 127.0.0.1 and click Properties
8. Under Aliases make sure you have the following entries in order
   1. first your server's fully qualified domain name, something like your_server_name.department.school.edu
   2. second your server's name, something like your_server_name
   3. third localhost
9. Click Add and add an entry with IP address 127.0.1.1 and under Aliases put your server's fully qualified domain name, something like your_server_name.department.school.edu
10. Then click OK
11. And click Close to close Network settings

Then check again by running the commands

$ hostname --fqdn

and

$ hostname

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

Now restart Apache

$ sudo apache2ctl graceful
Password: <wwadmin password>

or

$ sudo service apache2 restart
Password: <wwadmin password>

and test your server by connecting to "http://localhost/" and/or connecting to your server from a browser on a remote machine. You should see the page It works! indicating that Apache is running.

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

Further test Apache by connecting to "http://localhost/server-info" using a browser on your machine (or or 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.2.22 (Ubuntu) mod_apreq2-20090110/2.8.0 mod_perl/2.0.5 Perl/v5.14.2

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

Checking MySQL

First check that MySQL is running by

$ mysql -u root -p 
Enter Password: <mysql root password>

You should see something very similar to

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

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

Enter exit to exit

mysql> exit
Bye
$

Checking Apache

Now connect to "http://localhost/" using a browser on your machine and/or to your server from a browser on a remote machine. You should see the page It Works indicating that Apache is running.

This is also a good time to check that you can login your server from a remote location using SSH if you have not yet done so (non secure telnet and FTP are not allowed but secure SSH and SFTP are). If you are using "SSH Secure Shell" (now called "SSH Tectia"), a popular SSH client for PC's, you will have to add Keyboard Interactive to the list of "Authentication methods" under "Authentication" if it's not already there.

MySQL Security and Performance Issuses

As initially set up, MySQL is an open system. There are anonymous accounts with full privileges for some databases and other issues. We will fix that now. Run the command

sudo mysql_secure_installation
Password: <wwadmin password>

You will be asked to enter the (MySQL) root password <mysql root password>. You almost certainly want to answer 'Y' (which is the default) to all questions except for the first which asks if you want to change the root password.

Now test that all is well:

$ mysql -u root -p 
Enter Password: <mysql root password>

You should see

Welcome to the MySQL monitor ...
mysql>

Now lets check the MySQL users. There are three or four root accounts, one is root@localhost, one is root@127.0.0.1, one is root@::1 and the fourth may be root@host_name where host_name is the name of your server. To see the accounts, do the following

mysql> SELECT Host, User, Password FROM mysql.user;

You will see a table with four or five users (three or four root and one debian-sys-maint). You should see that all four or five users have passwords (which will be displayed in encrypted form).

Now exit MySQL

mysql> exit
Bye
$

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. Note: There is a report of a problem using MyISAM by a French speaking professor who changed MySQL's default character set to utf8 (see http://webwork.maa.org/moodle/mod/forum/discuss.php?d=3174). If you change MySQL's default character set, you should research what is the best engine to use.

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

$ cd /etc/mysql
$ sudo cp my.cnf my.cnf.bak1
Password: <wwadmin password>
$ sudo gedit my.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
password: <wwadmin password>

or

$ sudo service mysql restart
password: <wwadmin password>

and log into mysql

$ mysql -u root -p 
Enter Password: <mysql root password>

You will see

Welcome to the MySQL monitor ...
mysql>

If you show MySQL engines, you should see that MyISAM is listed as the default engine.

mysql> SHOW ENGINES\G

Now exit

mysql> exit
Bye
$

Remove Guest Account Login

Ubuntu allows a guest login which we will remove. In a terminal window run the commands

$ cd /etc/lightdm/
$ sudo cp lightdm.conf lightdm.conf.bak1
Password: <wwadmin password>
$ sudo gedit lightdm.conf

At the end (below the last line) add the new line

allow-guest=false

Then save the file and quit.

Congratulate yourself. You are now ready for the next and hopefully easy part, installing WeBWorK.

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>) 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
$ git clone git://github.com/mathjax/MathJax.git MathJax

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.7 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 relecct its growing international content. Your system will be loaded with many thousands of WeBWorK problems (over 25,000 currently). The fourth download is MathJax which is one of several options WeBWorK has to display mathematics online.

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

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

The main information page about MathJax is available at http://www.mathjax.org/

Installing WeBWorK

Note the 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 wwadmin and move directories there.

$ sudo mkdir /opt/webwork
<wwadmin password>
$ sudo chown wwadmin:wwadmin /opt/webwork
$ mv webwork2 /opt/webwork/
$ mv pg /opt/webwork/

Move the mathjax directory to its proper location

$ mv mathjax /opt/webwork/webwork2/htdocs/

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 wwadmin 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 wwadmin 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 create a new group called wwdata, containing both the WeBWorK administrators and the web server. Run the commands

$ sudo addgroup wwdata
<wwadmin password>
$ sudo adduser wwadmin wwdata

If there are other users who will also be administering WeBWorK files, now is a good time to add them. To do this

1. Open Dash Home, type User and open User Accounts
2. Click the "Unlock" icon and enter the <wwadmin password>
3. Click the "+" icon and create the new account
4. And remember to add the new account to the wwdata group as above.

Now add the Apache2 webserver (which runs as www-data) to the wwdata group:

$ sudo adduser www-data wwdata

You can check that this succeeded in a terminal window by entering

$ id wwadmin

and then you should see wwdata listed under groups. Also

$ id www-data

should show wwdata listed under groups. Now we make the WeBWorK directories that need to be writable by the web server have wwdata 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.

$ su
Password: <root password>
# cd /opt/webwork/webwork2/
# chgrp -R wwdata DATA ../courses htdocs/tmp logs tmp
# chmod -R g+w DATA ../courses htdocs/tmp logs tmp
# find DATA/ ../courses/ htdocs/tmp logs/ tmp/ -type d -a -exec chmod g+s {} \;
# exit
$

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

$ gedit .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 Dependancies

WeBWorK includes a script called check_modules.pl 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 except tth which is a deprecated display mode. If something is missing (flagged by **), look back through these instructions and/or look at Installation Manual for 2.4 to find where it should have been installed and install it. Note you may have to search in Installation Manual for 2.4 to find out what package it is contained in.

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 edit the course.conf file for herself (for her own course) 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 WeBWoeK but it's 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 WeBWoeK but it's 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
$ gedit 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. If you are running a secure server (i.e., using ssl), the url will probably start with https.

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 password the MySQL root user uses. 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. 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.

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 go to http://search.cpan.org/dist/DateTime-TimeZone/ . These timezones are more refined than standard timezone 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 DateTime::TimeZone::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 timezones and formatting dates.

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

Then save the file and Quit.

The defaults.config file

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

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

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

Edit the localOverrides.conf file

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

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

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

removing the # and using the professor(s) actual email address(es). In order to have professors from individual courses receive such email, this should be set in course.conf (which you find in the course directory) to the addresses of professors of each course. Note that the settings in course.conf override the settings in site.conf, default.conf and localOverrides.conf so if in addition you want e.g. the WeBWorK administrators to receive copies, you have to add them as well.

Next we set up the Open Problem Library. Search for $problemLibrary{root} and replace that line by

$problemLibrary{root}        ="/opt/webwork/libraries/webwork-open-problem-library/OpenProblemLibrary";

Note that above we have the directory libraries not library.

Then save the file and Quit.

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

$ mysql -u root -p 
Enter password: <mysql root password>
mysql> CREATE DATABASE webwork;
mysql> GRANT SELECT, INSERT, UPDATE, DELETE, CREATE, ALTER, DROP, LOCK TABLES ON webwork.* TO webworkWrite@localhost IDENTIFIED BY 'database_password';
mysql> exit
Bye
$ 

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

jsMath Settings

Version 2.0 of jsMath introduced a new fallback method for when the TeX fonts are not available on the student's computer. This uses images of the individual TeX characters in place of the TeX fonts. These are distributed in webwork2/htdocs/jsMath/jsMath-fonts.tar.gz, and you need to unpack this tarball before jsMath will work properly. Use the command

$ cd /opt/webwork/webwork2/htdocs/jsMath
$ tar vfxz jsMath-fonts.tar.gz

This will unpack the archive. Since there are 20,000 tiny files, it can take a little while, so the v option is used to show you the names as they are unpacked so that you know the command is actually doing something. Once the images are unpacked, jsMath's image mode fallback (the default fallback method) will work properly.

MathJax

General information on MathJax can be found at http://www.mathjax.org/ and general installation instructions are at http://www.mathjax.org/resources/docs/?installation.html . MathJax is already installed in the location /opt/webwork/webwork2/htdocs/mathjax

Configuring Apache

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

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

and now link it into your Apache configuration process

$ su
<root password>
# cd /etc/apache2/conf.d
# ln -s /opt/webwork/webwork2/conf/webwork.apache2-config webwork.conf

Next we will make a few changes to Apache's default configuration. First we backup the configuration file

# cd /etc/apache2/
# cp apache2.conf apache2.conf.bak1
# exit
$ cd /etc/apache2/
$ sudo gedit apache2.conf

Search for the line

Timeout 300

and replace it by

Timeout 1200

Next seach for the lines

    MaxClients          150
    MaxRequestsPerChild   0

Which occur under <IfModule mpm_prefork_module> and replace them by

# For WeBWorK a rough rule of thumb is 20 MaxClients per 1 GB of memory
    MaxClients           20
    MaxRequestsPerChild  100

where you should set MaxClients depending on the amount of memory your server has using the above rule of thumb.

NOTE: If you are using Apache version 2.4 or higher (available in Ubuntu 3.10 and later) you should use MaxRequestWorkers instead of MaxClients and MaxConnectionsPerChild instead of MaxRequestsPerChild. Furthermore, in Apache 2.4 these directives are stored in the file /etc/apache2/mods-enabled/mpm_prefork.conf.

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
Password: <wwadmin password>

Now restart Apache

$ sudo apache2ctl graceful

Test your configuration

1. 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.
2. Test the /webwork2_files location by visiting http://yourserver.yourschool.edu/webwork2_files. You should see the "WeBWorK Placeholder Page".
3. 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-config webwork.apache2-config.dist 

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

$ sudo apache2ctl graceful
Password: <wwadmin password>

Create the admin Course

Course Administration gives information about creating courses. Here we will give explicit instructions for doing this.

$ newgrp wwdata
$ umask 2
$ cd /opt/webwork/courses
$ /opt/webwork/webwork2/bin/addcourse admin --db-layout=sql_single --users=adminClasslist.lst --professors=admin
$ exit

Now goto http://yourserver.yourschool.edu/webwork2 and should see the WeBWorK home page with Course Adninistration 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. The next thing you should do is click on Password/Email and change admin 's password to something more secure than admin .

Unless you choose oherwise, users with professor privilges in the admin course (i.e. WeBWorK administrators) will automatically be added to new courses with professor privilges 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 )

1. Click on Classlist Editor in the left panel
2. Check Add 1 student(s) and click Take Action!
3. Enter the appropiate information (you can leave the last three items blank) and click Add Students
4. Click on Classlist Editor in the left panel again

1. When you enter a new student, by default their Student ID is used as their password. We'll change this now.
2. Select yourself with a check mark and then check Give new password to Selected users or just check Give new password to All users (as a safely mechanism you can not change the password for the user you are logged in as, currently admin, this way) and then click Take Action!
3. Enter the password, check Save changes and then click Take Action!
4. Finally give yourself professor privilges by selecting yourself with a check mark, checking Edit Selected users 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)
5. Now at the far right change Permission Level from student to professor
6. Check Save changes and 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.7 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:

/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

Updating MathJax

cd /opt/webwork/webwork2/htdocs/mathjax/
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

Updating MathJax is usually very safe and does not require restarting apache2.

Starting and Stopping Apache, MySQL and the GNOME desktop GUI

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
password:<wwadmin password>

You can also start apache2 by

$ sudo apache2ctl start
password:<wwadmin password>

and restart it with

$ sudo apache2ctl restart
password:<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
password:<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
password:<wwadmin password>

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

Starting and Stopping MySQL

You have to run these commands as root.

To start the MySQL server run the command

$ sudo /etc/init.d/mysql start
password:<wwadmin password>

To stop the MySQL server run the command

$ sudo /etc/init.d/mysql stop
password: <wwadmin password>

To restart the MySQL server run the command

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

Starting and stopping the GNOME desktop GUI

The GNOME desktop is automatically started when the system boots.

To stop GNOME so that you only have a standard terminal window run the following in a standard terminal window

$ sudo /etc/init.d/lightdm stop 
password: <wwadmin password>

After doing this, if you need to use the server for terminal input, type <Ctrl><Alt><F1> to get a command line terminal.

If you stopped GNOME and want to restart it run the following in a standard terminal window

$ sudo /etc/init.d/lightdm start 
password: <wwadmin password>

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.

Run the OPL-update script.

$ OPL-update

This has to convert a lot of data for over 25,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 simpler. Optionally remove the previous copy of the library, unpack the new copy in the same place, and run OPL-update.

Finally 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

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

First we need to edit localOverrides.conf one last time

$ cd /opt/webwork/webwork2/conf
$ gedit 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 National Problem Library. Note that the Rochester, Union and other libraries are contained in the National Problem Library and are accessible from there under the NPL 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/NationalProblemLibrary/Union unionLibrary
$ ln -s /opt/webwork/libraries/NationalProblemLibrary/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/NationalProblemLibrary/ 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.

First we have to install svn

$ sudo apt-get install subversion
Password: <wwadmin password>

Just hit <Enter> to accept the defaults. After the installation is complete

Next we download the CAPA Library including required macros.

$ cd
$ cd downloads
$ svn co http://svn.webwork.maa.org/rochester/trunk/rochester_physics_problib

Create a CAPA directory under /opt/webwork and move the CAPA macros there. Then move the CAPA graphics and library files to the required locations and set the group.

$ mkdir /opt/webwork/libraries/CAPA
$ cd rochester_physics_problib/macros/                   
$ mv CAPA_Tools /opt/webwork/libraries/CAPA/                       
$ mv CAPA_MCTools /opt/webwork/libraries/CAPA/                     
$ cd ..                                                                          
$ mv CAPA_Graphics /opt/webwork/webwork2/htdocs/
$ sudo chgrp -R wwdata /opt/webwork/webwork2/htdocs/CAPA_Graphics
  password: <wwadmin password>
$ sudo chmod -R g+w /opt/webwork/webwork2/htdocs/CAPA_Graphics        
$ cd ..                                                  
$ mv rochester_physics_problib /opt/webwork/libraries/

We need to edit localOverrides.conf again

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

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

#      capaLibrary      => "CAPA",

Uncomment this line (i.e. remove the #) so it becomes

      capaLibrary      => "CAPA",

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/rochester_physics_problib/ capaLibrary

More likely you just want to do this for individual courses. 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/rochester_physics_problib/ capaLibrary
password: <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.

Create Your First Actual Course

Since we have edited global.conf a lot and this is a very critical file, it would be a good idea to run

$ cd /opt/webwork/webwork2/conf
$ diff global.conf global.conf.dist

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 global.conf, you must restart the Apache webserver in order for these changes to take effect.

Since we have edited global.conf extensively and haven't restartes Apache we do so now.

$ sudo apache2ctl graceful
password:<wwadmin password>

Now log into the admin course ( http://yourserver.yourschool.edu/webwork2/admin ) as yourself or admin and

1. click on Add Course
2. For Course ID enter myTestCourse
3. For Course Title enter My Test Course
4. Enter your institution
5. Leave Add WeBWorK administrators to new course checked
6. Add an additional instructor if you wish
7. Copy templates from: modelCourse (the default action)
8. Select sql_single for the database layout (the default action)
9. Click on Add Course
10. Click Log into myTestCourse

and log in either as admin or yourself.

At some point you will probably want to "hide" myTestCourse from general view but you already know how to do that.

Test that Things are Working Properly

We will test out a few important parts of WeBWorK. If you run into problems, you should look at the Apache error log which is located at /var/log/apache2/error.log.

Click on Hmwk Sets Editor on the Main Menu. Then select (by clicking the circle button) Import, select setDemo.def from the from drop down list and select all current users from the assigning this set to drop down list. Then hit Take Action!

Now click on Homework Sets on the Main Menu and click on Demo. Then look at the problems. Mathematical equations should be typeset. If not, edit the file Constants.pm in the directory /opt/webwork/webwork2/lib/WeBWorK. Change the line $WeBWorK::PG::ImageGenerator::PreserveTempFiles = 0; to ...::PreserveTempFiles = 1;. Then restart Apache and view the first couple problems or some new ones. Then look in the directory /opt/webwork/webwork2/tmp/. cd to one of the ImageGenerator.../tmp/ directories and look at the error and log files there. When you fix the problem remember to edit ...::PreserveTempFiles = 1; 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.

When you continue looking at problems you will probably get an error when you try to look at Problem 6 because you may not have configured the CAPA macros which are required to display CAPA problems. Unless you are teaching physics you probably don't need them. Also in Problem 9 the Java applet will not load. Problem 9 was written in the 90's and used an applet on a server at The Johns Hopkins University. The server went away a long time ago but we have retained this problem for historical reasons and also because it is a example of several things (e.g. WeBWorK problems can include applets running on remote servers but this can lead to other problems).

Next click on Prob. List to bring back the Problem List Page and click on Download a hardcopy of this homework set. The page is a little complicated because you are a professor (students see a very simple page) but you can just scroll to the bottom and click on Generate hardcopy for selected users and selected sets. You may get an error (because of the bad Problem 6) but just click Download Hardcopy 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 $WeBWorK::ContentGenerator::Hardcopy::PreserveTempFiles to 1 in the file Constants.pm in the directory /opt/webwork/webwork2/lib/WeBWorK and then restart Apache. Remember to set this back to 0 after debugging.

Another thing to do is to use Email on the Main Menu. 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 Send Email 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.

As a final test click on Library Browser on the Main Menu. Click Problem Library and select a Subject, Chapter and Section and then hit View Problems. 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.

If all the above tests work, you can be pretty confident that WeBWorK is working properly.

Go back to Hmwk Sets Editor on the Main Menu. Then select (by clicking the circle button) Import, select setOrientation.def from the from drop down list and select all current users from the assigning this set to drop down list. Then hit Take Action!. Then go through the Orientation problems. This is a good first set to use for introducing students to WeBWorK.

If you are new to WeBWorK, 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 interface. Click on Classlist Editor on the Main Menu. Then select (by clicking the circle button) Add 1 student(s)and hit Take Action!. Add one student, say Jane Smith, with Student ID 1234 and Login Name jsmith. Jane Smith's initial password will be her Student ID 1234. Now login as Jane Smith and play around a little.

Optional Configurations

Optional A stores WeBWorK's "temporary" files in a separate partition (or directory). Optional B installs and configures a lightweight webserver to serve static files. Optional C configures Apache so that access to WeBWorK will be through SSL.

Implement Optional A (wwtmp)

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 wwtmp as a separate partition, you first have to create the directory /var/www/wwtmp.

All of WeBWorK's "temporary" files will be stored under /var/www/wwtmp. 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.

First we set the group and permissions for the wwtmp directory

$ su
<root password>
# cd /var/www
# chown wwadmin wwtmp
# chgrp wwdata wwtmp
# chmod ug+w wwtmp
# chmod g+s wwtmp
# exit
$

Next we have to edit localOverrides.conf so that WeBWorK uses the new wwtmp directory. Since we have a working WeBWorK system, first we make a backup copy of localOverrides.conf.

$ cd /opt/webwork/webwork2/conf
$ cp localOverrides.conf localOverrides.conf.bak1
$ gedit localOverrides.conf

Now edit localOverrides.conf. Search for the line

# Directory for temporary files

and under that find the line

# To implement, uncomment the following 6 lines:

Then uncomment (i.e. remove the # symbol) from the 6 lines

#$webworkDirs{htdocs_temp}  =  '/var/www/wwtmp';
#$webworkURLs{htdocs_temp}   = '/wwtmp';
#$webworkDirs{equationCache} = "$webworkDirs{htdocs_temp}/equations";
#$webworkURLs{equationCache} = "$webworkURLs{htdocs_temp}/equations";
#$courseDirs{html_temp}  =  "/var/www/wwtmp/$courseName";
#$courseURLs{html_temp}   = "/wwtmp/$courseName";

Then save the file and quit. If you look at the wwtmp 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 wwtmp. Remember your have to restart apache for these changes to take effect.

Using Cron Jobs to remove temporary files

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 (wwtmp/.../hardcopy) 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 wwtmp 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 crontab to edit the crontab file:

$ su
<root password>
# crontab -e

Now add the lines

WEBWORK_ROOT=/opt/webwork/webwork2
*/30 * * * * find /var/www/wwtmp/*/hardcopy/*  -mmin +60  -name "*" -delete
5 5 1,15 * *  find /var/www/wwtmp/*/gif/  -mtime +30  -name "*" -delete
5 5 2,16 * *  find /var/www/wwtmp/*/png/  -mtime +30  -name "*" -delete
5 5 3,17 * *  find /var/www/wwtmp/*/html/  -mtime +30  -name "*" -delete
4 5 * * 0 /opt/webwork/webwork2/bin/remove_stale_images --delete --days 14

and save the file and quit

# exit
$

Implement Optional B (lighttpd)

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 and pages will be served by a light weight web server.

First we install the light weight webserver lighttpd

1. Open the Synaptic Package Manager (select Dash Home and type Synaptic and click on the Synaptic Package Manager icon). You will have to enter the <wwadmin password>. The Synaptic Package Manager window will open).
2. Select Search
3. Search for lighttpd and select it
4. In the pop up window Mark additional required changes? click Mark to accept the requirements.
5. Now click Apply and Apply again to confirm the changes.

You can now quit the Synaptic Package Manager.

Now we configure lighttpd. First let's make a backup of the configuration file.

$ su
<root password>
# cd /etc/lighttpd
# cp lighttpd.conf lighttpd.conf.bak1

Now edit lighttpd.conf.

# gedit lighttpd.conf

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

Find the line

server.document-root        = "/var/www"

and right above it add the new line

server.port               = 8080

Then save the file and quit.

Now restart lighttp

$su
<root password>
# /etc/init.d/lighttpd restart
# exit
$
 

Note that you can just run /etc/init.d/lighttpd to get a list of all options.

Now test your server by connecting to "http://localhost:8080/" and/or connecting to your server from a browser on a remote machine. You should see the page It works! indicating that lighttp is running.

Next we configure WeBWorK to take advantage of lighttp.

First let's make a backup copy of global.conf so that we can easily back out of these changes if necessary.

$ cd /opt/webwork/webwork2/conf
$ cp localOverrides.conf localOverrides.conf.bak2

Now edit localOverrides.conf. 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 localOverrides.conf assuming that Optional A has been implemented. If this is not the case, modify the instructions below accordingly. Also replace yourserver.yourschool.edu with the correct address.

# gedit localOverrides.conf

Find the line

$webworkURLs{htdocs_temp}   = '/wwtmp'

and replace it by

#$webworkURLs{htdocs_temp}   = '/wwtmp';
$webworkURLs{htdocs_temp}   = 'http://yourserver.yourschool.edu:8080/wwtmp';

Find the line

$courseURLs{html_temp}   = "/wwtmp/$courseName";

and replace it by

#$courseURLs{html_temp}   = "/wwtmp/$courseName";
$courseURLs{html_temp}   = "http://yourserver.yourschool.edu:8080/wwtmp/$courseName";

Then save the file and quit.

Now restart apache and lighttp.

$ sudo apache2ctl graceful
password:<wwadmin password>
$ sudo /etc/init.d/lighttpd restart

To test things go to your test course http://yourserver.yourschool.edu/webwork2/myTestCourse/. Log into your course and view a problem with typeset equations (e.g. Problem 1 of the Demo set). Right click on the typeset equation 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 http://yourserver.yourschool.edu:8080/wwwtmp/equations/...).

Disabling Optional B (lighttpd) for a single course

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 course.conf file which is located in the top level directory for the course (usually /opt/webwork/courses/course_name). Note that using apache instead of lighttpd will put a slightly larger load on the server.

# Do not use lightppd (port 8080) for this course
$webworkURLs{htdocs_temp}   = '/wwtmp';
$courseURLs{html_temp}   = "/wwtmp/$courseName";
$webworkURLs{equationCache} = "$webworkURLs{htdocs_temp}/equations";

Implement Optional C (SSL)

Optional C configures apache so that access to WeBWorK will be through an encrypted Secure Sockets Layer (SSL) with an https: URL. Note that if you implemented Optional B, the non encrypted lighttp server will be used for images, etc but there is no harm in that.

I cribbed these directions from several sources, the main one being http://www.akadia.com/services/ssh_test_certificate.html.

We will create and work in a tmp directory.

$ cd
$ mkdir tmp
$ cd tmp

First we create an RSA Private Key.

$ openssl genrsa -des3 -out server.key 1024

When you are asked for a pass phrase, enter a phrase which we refer to as <my pass phrase> and then confirm it. Next generate a Certificate Signing Request

$ openssl req -new -key server.key -out server.csr

Enter the requested information. Important: when you are prompted for the Common Name enter your server's fully qualified domain name, something like yourserver.yourschool.edu. You can leave the last two items

A challenge password []:
An optional company name []:

blank.

One unfortunate side-effect of the pass-phrased private key is that Apache will ask for the pass-phrase each time the web server is started. Obviously this is not necessarily convenient as someone will not always be around to type in the pass-phrase, such as after a reboot or crash. We will remove this but you must keep this file secure.

$ cp server.key server.key.bak1
$ openssl rsa -in server.key.bak1 -out server.key

Next we generate a self-signed certificate which is good for 365 days

$ openssl x509 -req -days 365 -in server.csr -signkey server.key -out server.crt

Now we become root, move these files, and set their group and permission.

$ su
<root password>
# mv server.crt /etc/ssl/private
# mv server.key /etc/ssl/private
# cd /etc/ssl/private
# chgrp ssl-cert server.*
# chmod 640 server.*

Next we enable the mod_ssl module

# a2enmod ssl
# exit

Now we have to configure Apache to use SSL.

$ cd /etc/apache2/sites-available/
$ sudo cp default default.bak1
Password: <wwadmin password>
$ sudo gedit default

Replace the first line

NameVirtualHost *

by the two lines

NameVirtualHost *:80
NameVirtualHost *:443

Now edit the next non blank line

<VirtualHost *>

changing it to

<VirtualHost *:80>

Next copy the entire section

<VirtualHost *:80> 
...
</VirtualHost>

(that is the whole VirtualHost section to the end of the file) and paste it into the file at the end of the file. Now we edit this new pasted section. Edit the new second

<VirtualHost *:80>

changing it to

<VirtualHost *:443>

Now at the end of the file just above the line

</VirtualHost>

add the three lines

    SSLEngine on
    SSLCertificateFile /etc/ssl/private/server.crt
    SSLCertificateKeyFile /etc/ssl/private/server.key

Then save the file and quit. Finally we restart Apache

# apache2ctl graceful

and test things. Connect to https://yourserver.yourschool.edu/webwork2/myTestCourse You will be asked to accept the certificate. After you do so things should work just as before except that all the connection will be via https (except for images, etc if you using lighttp).

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

$ sudo gedit default
Password: <wwadmin password>

In the

<VirtualHost *:80>

section just above the line

	ScriptAlias /cgi-bin/ /usr/lib/cgi-bin/

add the line

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

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

$ sudo apache2ctl graceful

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

Don't forget to update the value of $server_root_url in webwork2/conf/site.conf to use https (i.e., https://yourserver.yourschool.edu/webwork2).

==Where to go From Here You should play around with myTestCourse e.g. click on Library Browser and browse the Problem Library.

Look at A day in the life of a WeBWorK instructor.

Read Course Administration for more information about creating courses.

Consult for other WeBWorK documentation for system administrators.

Using Newer Ubuntu Releases

In general these instructions will work for newer versions of Ubuntu and WeBWorK, however there are some incompatibilities.

Ubuntu 13.10, Apache 2.4 and WeBWorK 2.8

WeBWorK 2.8 is incompatible with Apache 2.4, which is shipped with Ubuntu 13.10 by default. In order to use WeBWorK on 13.10 you will need to use a version of WeBWorK that is 2.9 or later. You can check your current version by looking at the webwork2/VERSION file. If you have version 2.8 you can use the develop branch instead. This is done using the command

git checkout origin develop

In addition you will need to use the file webwork-apache2.4-config.dist instead of webwork.apache2-config.dist. Otherwise the instructions in Configuring Apache are the same:

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

and now link it into your Apache configuration process

$ su
<root password>
# cd /etc/apache2/conf.d
# ln -s /opt/webwork/webwork2/conf/webwork.apache2.4-config webwork.conf

In addition the apache configuration process has changed. The directives MaxClients and MaxConnectionsPerChild are no longer used. Instead open the file /etc/apache2/mods-enabled/mpm_prefork.conf and search for the lines

MaxRequestWorkers 150
MaxConnectionsPerChild 0

and replace them by

# For WeBWorK a rough rule of thumb is 20 MaxClients per 1 GB of memory
MaxRequestWorkers           20
MaxConnectionsPerChild  100

where you should set MaxConnectionsPerChild depending on the amount of memory your server has using the above rule of thumb. After making these changes you will need to restart your server.

-- Main.ArnoldPizer - 1 June 2012