https://webwork.maa.org/mediawiki_new/api.php?action=feedcontributions&user=Xiong+Chiamiov&feedformat=atomWeBWorK_wiki - User contributions [en]2024-03-29T00:07:54ZUser contributionsMediaWiki 1.34.0https://webwork.maa.org/mediawiki_new/index.php?title=Specialized_contexts&diff=3879Specialized contexts2009-10-21T00:27:32Z<p>Xiong Chiamiov: add new Reaction context</p>
<hr />
<div>=== Specialized Contexts ===<br />
<br />
Using advanced methods one can customize Contexts to control the possible student responses that are allowed <br />
and the feedback given to students if their response has incorrect syntax. <br />
These customizations can be placed in a macro file for reuse which by convention is given a <br />
name starting with "context" -- e.g. <code>contextYourContextHere.pl</code>.<br />
<br />
The page [[ModifyingContexts(Advanced)]] contains information on the techniques and commands for doing this. <br />
<br />
Examples are provided in the files listed below.<br />
<br />
The other advanced method for customizing MathObjects is to modify the parser which <br />
translates "TI calculator" formulae into MathObjects. See [[SpecializedParsers]]<br />
<br />
=== Specialized Context Macro files ===<br />
Here is a partial list of contexts. <br />
Check the [http://webwork.maa.org/doc/cvs/pg_CURRENT/ POD documentation for more examples.]<br />
Use <code>loadMacros("contextABCD.pl");</code> to make the context available for a WeBWorK question.<br />
<br />
* [http://webwork.maa.org/doc/cvs/pg_CURRENT/macros/contextABCD.pl.html contextABCD.pl]<br />
** <code>Context("ABCD");</code><br />
** <code>Context("ABCD-List");</code><br />
** Contexts for matching problems. Adds strings A, B, C, D as allowable entries.<br />
* [http://webwork.maa.org/doc/cvs/pg_CURRENT/macros/contextCurrency.pl contextCurrency.pl]<br />
** <code>Context("Currency");</code><br />
** Context for entering numbers with currency symbols and commas.<br />
* [http://webwork.maa.org/doc/cvs/pg_CURRENT/macros/contextFraction.pl.html contextFraction.pl]<br />
** Implements a MathObject class for Fractions.<br />
* [http://webwork.maa.org/doc/cvs/pg_CURRENT/macros/contextInequalities.pl contextInequalities.pl]<br />
** <code>Context(`Inequalities');</code><br />
** <code>Context(`Inequalities-Only');</code><br />
** Provides contexts that allow intervals to be specified as inequalities.<br />
* [http://webwork.maa.org/doc/cvs/pg_CURRENT/macros/contextIntegerFunctions.pl contextIntegerFunctions.pl]<br />
** <code>Context("IntegerFunctions");</code><br />
** adds integer related functions C(n,r) and P(n,r).<br />
* [http://webwork.maa.org/doc/cvs/pg_CURRENT/macros/contextLimitedComplex.pl contextLimitedComplex.pl]<br />
** <code>Context("LimitedComplex");</code><br />
** Allow complex numbers but not complex operations.<br />
* [http://webwork.maa.org/doc/cvs/pg_CURRENT/macros/contextLimitedNumeric.pl contextLimitedNumeric.pl] <br />
** ( [DEPRECATED] -- loadMacros("contextLimitedNumeric.pl") is not needed, these contexts are now standard and defined in <code>pg/lib/Parser/Legacy/LimitedNumeric.pm</code><br />
** <code>Context("LimitedNumeric");</code><br />
** <code>Context("LimitedNumeric-List");</code> -- allows lists -- (need contextLimiteNumeric.pl for this)<br />
** <code>Context("LimitedNumeric-Fraction")</code><br />
** <code>Context("LimitedNumeric-StrictFraction");</code> -- no decimals<br />
** Allows numeric entry but no operations.<br />
* [http://webwork.maa.org/doc/cvs/pg_CURRENT/macros/contextLimitedPoint.pl contextLimitedPoint.pl]<br />
** <code>Context("LimitedPoint")</code><br />
** Allow point entry but no point operations.<br />
* [http://webwork.maa.org/doc/cvs/pg_CURRENT/macros/contextLimitedPolynomial.pl contextLimitedPolynomial.pl]<br />
** <code>Context("LimitedPolynomial");</code><br />
** Allow only entry of expanded polynomials.<br />
* [http://webwork.maa.org/doc/cvs/pg_CURRENT/macros/contextLimitedPowers.pl contextLimitedPowers.pl]<br />
** <code>LimitedPowers::NoBaseE();</code><br />
** <code>LimitedPowers::OnlyIntegers();</code><br />
** <code>LimitedPowers::OnlyPositiveIntegers();</code><br />
** <code>LimitedPowers::OnlyNonNegativeIntegers();</code><br />
** Restrict the base or power allowed in exponentials.<br />
* [http://webwork.maa.org/doc/cvs/pg_CURRENT/macros/contextLimitedVector.pl contextLimitedVector.pl]<br />
** <code>Context("LimitedVector-coordinate");</code><br />
** <code>Context("LimitedVector-ijk");</code><br />
** <code>Context("LimitedVector");</code> # either one<br />
** Allow vector entry but no vector operations.<br />
* [http://webwork.maa.org/doc/cvs/pg_CURRENT/macros/contextOrdering.pl.html contextOrdering.pl]<br />
** Parses ordered lists of letters like ``B > A = C > D''<br />
* [http://webwork.maa.org/doc/cvs/pg_CURRENT/macros/contextPeriodic.pl contextPeriodic.pl]<br />
** [DEPRECATED] Features added to Real and Complex MathObjects classes.<br />
* [http://webwork.maa.org/doc/cvs/pg_CURRENT/macros/contextPiecewiseFunction.pl contextPiecewiseFunction.pl]<br />
** <code>Context("PiecewiseFuntion");</code><br />
** Allow usage of piecewise functions.<br />
<br />
* [http://webwork.maa.org/doc/cvs/pg_CURRENT/macros/contextReaction.pl contextReaction.pl]<br />
** <code>Context("Reaction");</code><br />
** Implements checmical reactions that can be specified and compared.<br />
<br />
* [http://webwork.maa.org/doc/cvs/pg_CURRENT/macros/contextScientificNotation.pl contextScientificNotation.pl]<br />
** <code>Context("ScientificNotation");</code><br />
** Allows entry of scientific notation. Tries hard to report useful error messages when student's answer is not in the proper format. <br />
** Experimental: may be renamed to LimitedScientifcNotation<br />
* [http://webwork.maa.org/doc/cvs/pg_CURRENT/macros/contextString.pl contextString.pl]<br />
** Use this context to allow restricted short answer (no mathematical symbols) questions.<br />
** Feedback is provided if the response contains strings that are not allowed. <br />
** See also [http://webwork.maa.org/doc/cvs/pg_CURRENT/macros/parserAutoStrings.pl.html parserAutoStrings.pl] <br />
* [http://webwork.maa.org/doc/cvs/pg_CURRENT/macros/contextTF.pl contextTF.pl]<br />
** <code>Context("TF");</code><br />
<br />
[[Category:Contexts]]</div>Xiong Chiamiovhttps://webwork.maa.org/mediawiki_new/index.php?title=Installation_Manual_for_2.4_on_Ubuntu_9.04&diff=5031Installation Manual for 2.4 on Ubuntu 9.042009-10-20T23:59:52Z<p>Xiong Chiamiov: /* Install and Set Up the CAPA Library */ a little bit of copy-editing</p>
<hr />
<div>These instructions cover the installation of the Ubuntu Linux 9.04 operating system and WeBWorK 2.4 from scratch. Note that you can also quickly install Ubuntu 9.04 and WeBWorK 2.4 from the WeBWorK Live DVD (see [[Installing from WW2.4_Ubuntu9.04_LiveDVD]]).<br />
<br />
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.<br />
<br />
== Notation ==<br />
<br />
First some short comments on notation we will be using. We will use <code>&lt;key&gt;</code> to indicate that you should press a specific key (e.g. <code>&lt;Enter&gt;</code>, <code>&lt;Tab&gt;</code>, <code>&lt;F12&gt;</code>, etc.). Sometimes we will also use e.g. <code>&lt;root password&gt;</code> to indicate you have to enter the root password.<br />
<br />
<code>^</code> will indicate the <code>&lt;Ctrl&gt;</code> key so e.g. <code>^X</code> is really shorthand for <code>&lt;Ctrl&gt; &lt;X&gt;</code>, i.e. press the Ctrl key and hit the X key.<br />
<br />
We will give references to specific versions of software, e.g. httpd-2.2.4.tar.gz rather than the more general httpd-2.x.x.tar.gz. In most cases you should be able to use the latest stable version but we have only tested the versions listed.<br />
<br />
== Installing the Ubuntu 9.04 Linux Operating System ==<br />
<br />
===Installation CD ===<br />
Obtain the <code>Desktop Edition, Alternate</code> installation DVD/CD set. Connect to http://www.ubuntu.com/ for information. On the download page http://www.ubuntu.com/getubuntu/download under "even more options" click on <code>Text based “alternate installer” installation disk</code>. For example you can use wxDownload Fast or BitTorrent to download an ISO image of the installation CD and then burn your own installation CD. You want the file <code>ubuntu-9.04-alternate-i386.iso</code>. 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/9.04/MD5SUMS). wxDownload Fast automatically calculates the MD5 checksums which is convenient. I have had good luck downloading from mirrors.kernel.org but your experience may differ. These instructions will assume you have the installation CD but installing from a commercial DVD/CD set or from the net should be essentially identical.<br />
<br />
Place the installation CD in your DVD/CD drive and reboot your computer from the DVD drive. You may have to press <code>&lt;F12&gt;</code> 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.<br />
<br />
First select <code>English</code> by just hitting <code>&lt;Enter&gt;</code>.<br />
<br />
You will see a list of options. <br />
<br />
# If you want hit <code>&lt;F1&gt;</code> to obtain help and see additional boot methods<br />
# You can just hit <code>&lt;Enter&gt;</code> to accept the default install method except in the following situation<br />
# If your network has DHCP enabled but you want to setup your server with a static IP address, first hit <code>&lt;F6&gt;</code> and then hit <code>&lt;Esc&gt;</code> to remove the box with additional options. Now on the <code>Boot Options</code> line use the back arrow key to move the cursor before <code>quiet --</code> and type <code>netcfg/disable_dhcp=true</code> , leave a space before <code>quiet</code> and then hit <code>&lt;Enter&gt;</code><br />
# A succession of pages follow, for each select the obvious option and hit <code>&lt;Enter&gt;</code>. For example my obvious options are <code>English</code>, <code>United States</code>, <code>&lt;No&gt;</code>, <code>USA</code> and <code>USA</code> <br />
# The system will than scan your CD and load various components<br />
# If your system has multiple network interfaces, you may be asked to select the one to be used during the installation (which will usually be a hard wired ethernet connection)<br />
# Unless you entered the <code>netcfg/disable_dhcp=true</code> boot option above, the system will try to configure your network using DHCP. If you have DHCP, your network interface will be set up automatically. If you don't have DHCP, automatic network configuration will fail quickly (or just hit <code>&lt;Enter&gt;</code> to <code>Cancel</code> if you are impatient). Then hit <code>&lt;Enter&gt;</code> to <code>Continue</code><br />
<br />
'''Manual network configuration'''. If your network interface was set up automatically by DHCP, you can skip the rest of this paragraph. Otherwise you will have to enter your machine's static ip address, etc. To do this<br />
# Select <code>Configure network manually</code><br />
# Enter your computer's IP address and use <code>&lt;Tab&gt;</code> to select <code>Continue</code><br />
# The <code>netask</code> is probably OK as it but another possibility may be 255.255.0.0<br />
# Enter the ip address of your gateway router. Ubuntu makes a good guess at this, but your network may be set up differently.<br />
# Next enter the ip address(es) of up to 3 nameservers separated by spaces (at a minimum you have to enter the ip address one nameserver)<br />
# Enter the name of your server<br />
# Enter the domain name for the domain your server sits on (e.g. math.myschool.edu)<br />
# This completes the static ip address setup<br />
<br />
Note: If at some point after the installation you want to change the ip address look at the directions in [[Installing from WW2.4_Ubuntu9.04_LiveDVD]].<br />
<br />
'''Finish the initial installation'''.<br />
# Enter the hostname of your server<br />
# Now select your time zone and wait for the clock to be configured<br />
<br />
===Optional Configurations===<br />
<br />
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.<br />
<br />
'''Optional A''' creates a separate partition 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 means that it is easier and faster to back up other partitions and skip backing up unnecessary files.<br />
<br />
'''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.<br />
<br />
'''Optional C''' configures Apache so that access to WeBWorK will be through an encrypted Secure Sockets Layer (SSL) with an https: URL.<br />
<br />
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.<br />
<br />
===Partition disks===<br />
Next comes the <code>Partition disks</code> 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. <br />
<br />
'''Optional A''': The default partitioning scheme creates just two partitions, a root (<code>/</code>) partition and a swap partition. Here we will create those and an additional partition for WeBWorK's temporary files.<br />
<br />
# On the <code>Partition disks</code> page use <code>&lt;Tab&gt;</code> to select <code>Go Back</code> and then select <code>Partition disks</code> <br />
# Use the down arrow to select your disk (<code>sda</code>)<br />
# On the <code>You have selected an entire device to partition...</code> page select <code>Yes</code> to the question <code>Create new empty partition table on this device</code><br />
# On the <code>This is an overview...</code> page select <code>FREE SPACE</code><br />
# On the <code>How to use this free space</code> page select <code>Create a new partition</code><br />
# 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 (<code>/</code>) partition. Actually if you are going through the trouble of doing this, you probably will want to research other partitioning recommendations.<br />
# On the <code>The maximum size you can use...</code> page enter the size for your root (<code>/</code>) partition and <code>Continue</code><br />
# Select <code>Primary</code> for the type of the new partition<br />
# Select <code>Beginning</code> for the location of the new partition<br />
# Select <code>/</code> for the Mount point of the new partition and then select <code>Done setting up the partition</code><br />
<br />
Now we repeat the process for the partition which will hold WeBWorK's temporary files.<br />
# On the <code>This is an overview...</code> page select <code>FREE SPACE</code><br />
# On the <code>How to use this free space</code> page select <code>Create a new partition</code><br />
# On the <code>The maximum size you can use...</code> page enter the size for WeBWorK's temporary files partition. As we said 25 GB for every 1,000 students should be ample. Then <code>Continue</code><br />
# Select <code>Logical</code> for the type of the new partition<br />
# Select <code>Beginning</code> for the location of the new partition<br />
# Select <code>Mount point</code> and then hit <code>&lt;Enter&gt;</code><br />
# Select <code>Enter manually</code> and then hit <code>&lt;Enter&gt;</code><br />
# For the <code>Mount point for this partition</code> enter <code>/var/www/wwtmp</code> and <code>Continue</code><br />
# Then select <code>Done setting up the partition</code><br />
<br />
Finally we set up the swap partition<br />
# On the <code>This is an overview...</code> page select <code>FREE SPACE</code><br />
# On the <code>How to use this free space</code> page select <code>Create a new partition</code><br />
# On the <code>The maximum size you can use...</code> 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 <code>Continue</code><br />
# Select <code>Logical</code> for the type of the new partition<br />
# Select <code>Beginning</code> for the location of the new partition<br />
# Select <code>Use as</code> and then hit <code>&lt;Enter&gt;</code><br />
# Select <code>swap area</code> and then hit <code>&lt;Enter&gt;</code><br />
# Then select <code>Done setting up the partition</code><br />
<br />
Finally <br />
# Review your changes and<br />
# Select <code>Finish partitioning and write changes to disk</code> and then hit <code>&lt;Enter&gt;</code><br />
# Select <code>Yes</code> to confirm the changes<br />
<br />
===Base Installation===<br />
# Now the base installation takes place --- this takes a short time<br />
# Enter yourself as a user (with user name and password). Note this account will function partially as the <code>root</code> account so you might want to pick a different username and password than you regularly use.<br />
# I responded <code>No</code> to encrypting my home directory<br />
# You can probably leave the HTTP proxy information blank<br />
# Now sit back and relax while a lot of software is installed --- this takes awhile<br />
<br />
The final step is to install the boot loader. I have a non standard setup and at one time I had trouble installing the Grub boot loader but Lilo worked fine. Grub worked for me with Ubuntu 9.04 and almost certainly will work for you<br />
<br />
===Continue Installation ===<br />
After this finishes the system will eject the CD and ask you to reboot. <br />
<br />
# Log into your account <br />
# At some point the <code>Update Manager</code> window may pop up. If it does, accept all updates. Alternately you can select <code>System</code>, <code>Administration</code>, <code>Update Manager</code>. Click <code>install Updates</code>. You may have to enter the <code>&lt;your password&gt;</code> which functions as the <code>&lt;root password&gt;</code> . Follow any instructions, e.g. you may be told to reboot as soon as the installation is completed (to reboot, click on your name in the upper right hand corner, then select <code>Restart</code>)<br />
<br />
===Test Browser and Keyboard ===<br />
<br />
After reboot and login, click on <code>Applications</code>, <code>Internet</code>, <code>Firefox Web Browser</code> (or just click the Firefox icon at the top of the screen) and you should be connected to the world. <br />
Goto <br />
http://webwork.maa.org/wiki/Installation_Manual_for_2.4_on_Ubuntu_8.04<br />
where you can view this document and, if you want, copy commands that you need (see below).<br />
<br />
If something is wrong and you are not connected to the web, the first thing to do is check that you entered the correct network information.<br />
# Select <code>System</code>, <code>Administration</code>, <code>Network</code><br />
# Click on <code>Unlock</code><br />
# Enter <code>&lt;your password&gt;</code> and click <code>Authenticate</code><br />
# Select <code>Wired connection</code> and click <code>Properties</code><br />
# Check that all the entries are correct and edit them if they are not<br />
# Then click <code>OK</code><br />
# Next click on <code>DNS</code> and check the name server entries and correct if necessary<br />
# Click on <code>Close</code> to close <code>Network settings</code><br />
Your network connection should start up almost immediately. If you are still having problems it's time to investigate further or seek help.<br />
<br />
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. Click <code>System</code>, <code>Preferences</code>, <code>Keyboard</code> and then increase the delay time interval and hit <code>Close</code>.<br />
<br />
== Terminal Window Notation and Use ==<br />
<br />
Before installing and configuring additional software, we need to talk about terminal windows.<br />
<br />
To open a terminal window click <code>Applications</code>, <code>Accessories</code> and then select <code>Terminal</code>.<br />
<br />
In a terminal window some commands will have to be run as root whereas<br />
others should be run as a regular user. We will use # to indicate<br />
that the command is to be run as root e.g.<br />
<br />
# perl -MCPAN -e shell<br />
<br />
and $ to indicate that the command is to be run as a normal user e.g.<br />
<br />
$ cp .bashrc .bashrc.bak1<br />
<br />
To execute the above commands you have to hit <code>&lt;Enter&gt;</code>. We'll just assume this. <br />
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.<br />
<br />
The bash shell which you will be using has a number of very<br />
convenient features.<br />
<br />
One is command and file name completion. If you are typing (e.g.<br />
<code>ch</code>) and hit <code>&lt;tab&gt;</code> bash will complete the command or filename if it is<br />
unambiguous (or more precisely it will complete as much as possible).<br />
If there are multiple possibilities (as in the case of <code>ch</code>) nothing will<br />
happen (except you may hear a beep) and you can type more letter(s) and hit <code>&lt;tab&gt;</code> again. Or you can<br />
hit <code>&lt;tab&gt;</code> a second time and you will see a list of all possible<br />
completions. E.g. entering <code>ch&lt;tab&gt;&lt;tab&gt;</code> gives a list of possible<br />
completions and <code>ch&lt;tab&gt;g&lt;tab&gt;</code> (or <code>chg&lt;tab&gt;</code>) gives <code>chgrp</code>, the change group command. This<br />
is very fast and convenient and it also leads to fewer typing errors.<br />
<br />
Another useful shortcut is the command history. Using the up and down<br />
arrow keys will bring up previous commands which can be edited and then<br />
executed. If you are repeating a command or entering a command which<br />
is similar to a previous one, this is very useful.<br />
<br />
You can copy commands from these instructions (with <code>copy</code> from the Edit dropdown list or <code>^C</code>) and paste them into a terminal window<br />
(with <code>paste</code> from the Edit dropdown list or <code>&lt;Shift&gt; &lt;Ctrl&gt; &lt;V&gt;</code>). 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 <code>database_password</code> with the correct code in the few places such things occur).<br />
<br />
By default Ubuntu has no password set for the root user. To gain root access you have to type in your own user password. This is the password you set for the first user while installing Ubuntu. However we will<br />
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:<br />
<br />
$ sudo passwd<br />
Password: <your password><br />
<br />
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'''.<br />
<br />
Enter new UNIX password: <root password><br />
Retype new UNIX password: <root password><br />
passwd: Password updated successfully<br />
$<br />
<br />
To test this <br />
<br />
$ su<br />
Password: <root password><br />
# whoami<br />
root<br />
# exit<br />
$<br />
<br />
Finally perhaps a safer way to run commands as <code>root</code> is to use the <code>sudo</code> command<br />
<br />
$ sudo <command><br />
Password: <your password><br />
<br />
After you enter the password the command is executed. For a certain period (maybe 5 minutes) you can execute additional <code>sudo</code> commands without reentering <code>&lt;your password&gt;</code>. A log of all <code>sudo</code> commands is kept (I don't know where). In these instructions for the most part we will not use <code>sudo</code>, but keep it in mind for other times that you have to become <code>root</code> in order to execute a few commands (e.g. restarting <code>Apache</code>).<br />
<br />
Note that for certain GUI tools such as the <code>Synaptic Package Manager</code> that require root access, the password required is <code>&lt;your password&gt;</code>, the password for the first account you set up, not the new <code>&lt;root password&gt;</code>.<br />
<br />
For our next terminal window task create a <code>downloads</code> directory where we will keep copies of downloaded software.<br />
<br />
$ cd<br />
$ mkdir downloads<br />
<br />
==Ubuntu Software Packages ==<br />
<br />
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 <code>Synaptic Package Manager</code> as follows.<br />
<br />
# Select <code>System</code>, <code>Administration</code> and then <code>Synaptic Package Manager</code>. You will have to enter the <code>&lt;your password&gt;</code>. The <code>Synaptic Package Manager</code> window will open<br />
# Click on <code>Reload</code> to bring the package information up to date<br />
<br />
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 <code>libnet-ldap-perl</code> and then just give the list of required packages.<br />
<br />
# Select <code>Search</code> <br />
# Under <code>Look in:</code> select <code>Name</code>. The default <code>Description and Name</code> sometimes returns too many possibilities<br />
# We are searching for <code>libnet-ldap-perl</code> so enter <code>ldap-perl</code> (or something similar; you can copy and paste from this document if you want) and click on <code>Search</code><br />
# This should result in 6 possibilities. Select and Mark for Installation (by double clicking or checking and then selecting <code>Mark for Installation</code>) <code>libnet-ldap-perl</code>. You will see a pop up window <code>Mark additional required changes?</code> and you should always click <code>Mark</code> to accept the requirements.<br />
# Follow this basic procedure for all the packages listed below<br />
<br />
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. <br />
<br />
# <code>apache2</code><br />
# <code>apache2-mpm-prefork</code><br />
# <code>cvs</code><br />
# <code>dvipng</code><br />
# <code>gcc</code><br />
# <code>libapache2-request-perl</code><br />
# <code>libdatetime-perl</code><br />
# <code>libdbd-mysql-perl</code><br />
# <code>libemail-address-perl</code><br />
# <code>libextutils-xsbuilder-perl</code><br />
# <code>libgd-gd2-perl</code><br />
# <code>libmail-sender-perl</code><br />
# <code>libnet-ldap-perl</code><br />
# <code>libossp-uuid-perl</code><br />
# <code>libsql-abstract-perl</code><br />
# <code>libstring-shellquote-perl</code><br />
# <code>libtimedate-perl</code><br />
# <code>libxml-parser-perl</code><br />
# <code>libxml-writer-perl</code><br />
# <code>make</code><br />
# <code>mysql-server-5.0</code><br />
# <code>netpbm</code><br />
# <code>openssh-server</code><br />
# <code>preview-latex-style</code><br />
# <code>tetex-bin</code><br />
# <code>tetex-extra</code><br />
# <code>unzip</code><br />
<br />
When I do this I see on the bottom of <code>Synaptic Package Manager</code> window <code>82 to install/upgrade</code>, <code>1 to remove</code>. Your numbers may differ slightly. <br />
Now click <code>Apply</code> and <code>Apply</code> again to confirm the changes. You will be asked to enter a<br />
<code>New password for the MySQL "root" user</code>. Enter your choosen MySQL <code>root</code> password. As was said above, '''Do not forget what you enter here'''. Also remember that this is the password for the MySQL <code>root</code> user, not the Ubuntu linux system <code>root</code> user. Below we refer to this as <code>&lt;mysql root password&gt;</code><br />
<br />
That completes the set up of your base Ubuntu system. You can quit the <code>Synaptic Package Manager</code>.<br />
<br />
<br />
If you would prefer to install all of these packages in one fell swoop, run this command as root:<br />
<br />
<code># aptitude install apache2 apache2-mpm-prefork cvs dvipng gcc libapache2-request-perl libdatetime-perl libdbd-mysql-perl libemail-address-perl libextutils-xsbuilder-perl libgd-gd2-perl libmail-sender-perl libnet-ldap-perl libossp-uuid-perl libsql-abstract-perl libstring-shellquote-perl libtimedate-perl libxml-parser-perl libxml-writer-perl make mysql-server-5.0 netpbm openssh-server preview-latex-style tetex-bin tetex-extra unzip</code><br />
<br />
In case you skipped by it, look above for information on the <code>New password for the MySQL "root" user</code>.<br />
<br />
== Installing Perl Modules ==<br />
We now have to install several additional Perl modules which unfortunately are not available from the Debian package system.<br />
<br />
=== Testing Perl Modules ===<br />
To test if a Perl module is installed and working on your system, issue the following command, replacing <code>Module</code> with the name of the module:<br />
<br />
$ perl -MModule -e 'print "installed!\n"'<br />
<br />
If the module is installed you will see <code>installed!</code>. If not you will see at lot of gibberish. E.g. at this stage in our installation process <code>CPAN</code> is installed and <code>MXML::Parser::EasyTree</code> is not so<br />
<br />
$ perl -MCPAN -e 'print "installed!\n"'<br />
<br />
yields<br />
<br />
installed!<br />
<br />
and<br />
<br />
$ perl -MXML::Parser::EasyTree -e 'print "installed!\n"'<br />
<br />
yields<br />
<br />
Can't locate XML/Parser/EasyTree.pm in @INC (@INC contains: <br />
/etc/perl /usr/local/lib/perl/5.8.8 /usr/local/share/perl/5.8.8<br />
...<br />
<br />
=== Installing Additional Perl Modules from CPAN ===<br />
<br />
Be aware that in rare cases you might have to <br />
as root run<br />
<br />
$ su<br />
<root password><br />
# unset LANG<br />
# exit<br />
$<br />
<br />
since otherwise the installation of some modules (Module::Build is an example) may fail.<br />
<br />
First we will set up CPAN. For this you have to be root.<br />
<br />
$ su<br />
<root password><br />
# perl -MCPAN -e shell<br />
<br />
Since this is the first time you are using CPAN it will ask you <code>Would you like me to configure as much as possible automatically?</code> <br />
Respond <code>Yes</code> and that should be it. <br />
<br />
Next we add at least one mirror and reload the index. A list of mirrors can be found at http://mirrors.cpan.org. I have had good luck with the mirror ftp://mirrors.kernel.org/pub/CPAN .<br />
<br />
<br />
To add the mirror ftp://mirrors.kernel.org/pub/CPAN and reload the index do the following. For me, a slow and inaccurate typist, copying (<code>^C</code>) and pasting (<code>&lt;Shift&gt; &lt;Ctrl&gt; &lt;V&gt;</code>) is much faster.<br />
<br />
cpan> o conf urllist push ftp://mirrors.kernel.org/pub/CPAN<br />
cpan> reload index<br />
<br />
Note that one time this failed when I tried to do it in the evening but when I tried again the next morning it worked fine. Now we update CPAN itself<br />
<br />
cpan> install Bundle::CPAN<br />
<br />
and always hit <code>&lt;Enter&gt;</code> to accept the defaults when prompted. This can be a long process with many long pauses. Please be patient. <br />
When you again see the <br />
<br />
cpan><br />
<br />
prompt enter<br />
<br />
cpan> reload cpan<br />
cpan> o conf commit<br />
<br />
Now install the following modules<br />
<br />
cpan> install XML::Parser::EasyTree Iterator Iterator::Util Net::IP <br />
<br />
and in case you are prompted accept all defaults by just hitting <code>&lt;Enter&gt;</code>. <br />
Note that with more than one module to install, we just list them after <code>install</code> separated by spaces.<br />
<br />
When you again see the <br />
<br />
cpan><br />
<br />
prompt enter<br />
<br />
cpan> exit<br />
#<br />
<br />
=== Installing Additional Perl Modules from Source ===<br />
At one point in time (August 2006), the installation of <code>DateTime</code> using CPAN was broken. Currently <code>DateTime</code> 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. <br />
<br />
'''IMPORTANT:''' With Ububtu we have already installed <code>DateTime</code> 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.<br />
<br />
Now we give the example of installing <code>DateTime</code> from source. As we said you can skip this part.<br />
<br />
Goto http://search.cpan.org/,<br />
search for <code>DateTime</code> and click on <code>DateTime</code>. Then near the top right download <code>DateTime-0.36.tar.gz</code> and save it to disk. Move it to your <code>downloads</code> directory. Then<br />
<br />
$ cd <br />
$ cd downloads<br />
$ tar -zvxf DateTime-0.36.tar.gz<br />
$ cd DateTime-0.36/<br />
<br />
<br />
$ perl Makefile.PL<br />
$ make<br />
$ make test<br />
<br />
If <code>make test</code> indicates something is missing you will have to install that. In fact in the case of <code>DateTime</code>, you would see that quite a few things are missing.<br />
<code>DateTime</code> requires the additional modules <code>version</code> , <code>Module::Build</code> , <code>Class::Singleton</code> , <code>DateTime::TimeZone</code> and <code>DateTime::Locale</code> . We could install these using CPAN<br />
<br />
# perl -MCPAN -e shell<br />
cpan> install version Module::Build Class::Singleton DateTime::TimeZone DateTime::Locale<br />
cpan> exit<br />
# exit<br />
$<br />
<br />
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<br />
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 <code>package/file.pm</code> was not found, you should serach for and install <code>package::file</code> since perl modules use a double colon (<code>::</code>) as a directory separator.<br />
<br />
Assuming all is OK<br />
<br />
$su<br />
<root password><br />
# make install<br />
# exit<br />
$<br />
<br />
Finally you should definitely test that the module (e.g. <code>DateTime</code>) was installed sucessfully<br />
<br />
$ perl -MDateTime -e 'print "installed!\n"'<br />
<br />
If you see <br />
<br />
installed!<br />
<br />
you can celebrate.<br />
<br />
== Apache 2 and mod_perl ==<br />
<br />
First we have to enable a couple Apache modules. Acting as <code>root</code> in a terminal window enter<br />
<br />
# a2enmod apreq<br />
# a2enmod info<br />
<br />
Next we make a copy of the configuration files for safekeeping. <br />
<br />
# cd /etc/apache2/mods-available<br />
# cp info.conf info.conf.bak1<br />
# cp status.conf status.conf.bak1<br />
<br />
Now we will edit configuration files <code>info.conf</code> and <code>status.conf</code> to allow us to view information about the setup and performance of the web server. Note that this is not absolutely necessary but it can be very useful. You can use your favorite editor but we will give instructions assuming you are using <code>gedit</code>. Note that you have to be root to edit these files. First we edit <code>info.conf</code><br />
<br />
# cd /etc/apache2/mods-available<br />
# gedit info.conf<br />
<br />
You will see a lot a warning messages since Ubuntu doesn't like you to run gedit as root. You can ignore these or use sudo instead.<br />
<br />
I suggest you allow access to server information from e.g. your department domain. To do this uncomment (i.e. remove the <code>#</code> from) <br />
# Allow from .example.com<br />
and then replace <code>.example.com</code> by <code>.math.yourschool.edu</code><br />
where of course you should edit <code>.math.yourschool.edu</code> appropriately. <br />
<br />
Then save the file and quit (<code>Save</code> and <code>File</code>, <code>Quit</code>).<br />
<br />
Now we edit <code>status.conf</code><br />
<br />
# cd /etc/apache2/mods-available<br />
# gedit status.conf<br />
<br />
After the comments at the top and above the <code><Location /server-status></code> line enter<br />
<br />
ExtendedStatus On<br />
<br />
Now edit the <br />
# Allow from .example.com<br />
line just as you did for <code>info.conf</code>.<br />
Then save the file and quit<br />
<br />
Now we have to set your server's fully qualified domain name. Note that if your network was set up automatically via DHCP, your server's fully qualified domain name should already be set up. You can check by running the <code>hostname</code> commands below.<br />
<br />
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 <code>gnome-network-admin</code> but the quickest way is to run the command<br />
$sudo apt-get install gnome-network-admin<br />
<br />
After this is installed<br />
<br />
# Select <code>System</code>, <code>Administration</code>, <code>Network</code><br />
# Click on <code>Unlock</code><br />
# Enter <code>&lt;your password&gt;</code> and click <code>Authenticate</code><br />
# Click on <code>General</code><br />
# Under <code>Host name</code> enter <code>your_server_name</code> (if it's not already there)<br />
# Then under <code>Domain name</code> enter your server's domain name, something like <code>department.school.edu</code><br />
<br />
Next<br />
# Click on <code>Hosts</code><br />
#There should also be an entry with your server's IP address (if not you should add one)<br />
# Select the entry with your server's IP address and click <code>Properties</code> (NOTE: with 9.04 clicking <code>Properties</code> 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)<br />
# Under Aliases you should see your server's fully qualified domain name, something like <code>your_server_name.department.school.edu</code><br />
# Add or edit these entries if they are not correct<br />
# Then click <code>OK</code><br />
# And click <code>Close</code> to close <code>Network settings</code><br />
<br />
You can check these settings by running the commands<br />
<br />
$ hostname --fqdn<br />
<br />
and <br />
<br />
$ hostname<br />
<br />
The first respond with the fully qualified domain name and the second with just <code>your_server_name</code>.<br />
<br />
If the command <code>hostname --fqdn</code> returns <code>Unknown host</code> do the following:<br />
<br />
# Select <code>System</code>, <code>Administration</code>, <code>Network</code><br />
# Click on <code>Unlock</code><br />
# Enter <code>&lt;your password&gt;</code> and click <code>Authenticate</code><br />
# Click on <code>Hosts</code><br />
# Select the entry with your server's IP address and click <code>Properties</code><br />
# Under Aliases you should see your server's fully qualified domain name, something like <code>your_server_name.department.school.edu</code><br />
# Select the entry <code>127.0.0.1</code> and click <code>Properties</code><br />
# Under Aliases make sure you have the following entries in order<br />
## first your server's fully qualified domain name, something like <code>your_server_name.department.school.edu</code><br />
## second your server's name, something like <code>your_server_name</code><br />
## third <code>localhost</code><br />
# Click <code>Add</code> and add an entry with <code>IP address</code> <code>127.0.1.1</code> and under <code>Aliases</code> put your server's fully qualified domain name, something like <code>your_server_name.department.school.edu</code><br />
# Then click <code>OK</code><br />
# And click <code>Close</code> to close <code>Network settings</code><br />
<br />
Then check again by running the commands<br />
<br />
$ hostname --fqdn<br />
<br />
and <br />
<br />
$ hostname<br />
<br />
Note that if your server can not find its fully qualified domain name, certain tools (such as the Synaptic Package Manager) will not start.<br />
<br />
Now restart Apache<br />
<br />
$su<br />
<root password><br />
# apache2ctl graceful<br />
# exit<br />
$<br />
<br />
and test your server by connecting to<br />
"http://localhost/" and/or connecting to your<br />
server from a browser on a remote machine. You should see the page '''It works!''' indicating that Apache is running.<br />
<br />
You can check Apache's status by connecting to<br />
"http://localhost/server-status" using a browser on your machine or from a browser on a remote machine in the math.yourschool.edu domain.<br />
<br />
Further test Apache by connecting to<br />
"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 <br />
information about Apache. In particular under <code>Server Settings</code> you should see<br />
<br />
Server Version: Apache/2.2.11 (Ubuntu) mod_apreq2-20051231/2.6.0 mod_perl/2.0.4 Perl/v5.10.0<br />
indicating that both <code>mod_apreq2</code> and <code>mod_perl</code> are installed.<br />
<br />
If you have problems now or in the future, a good first thing to do is to look at the Apache error log which is located at <code>/var/log/apache2/error.log</code>. In the directory <code>/var/log/apache2/</code> you can "less" through the error log (<code>less error.log</code>), look at the last few entires (<code>tail error.log</code>) or run the command <code>tail -f error.log</code> which will display new error messages as they are appended to the file. Use <br />
<code>^C</code> to break out of <code>tail -f</code> .<br />
<br />
== Checking MySQL ==<br />
<br />
First check that MySQL is running by <br />
<br />
$ mysql -u root -p <br />
Enter Password: <mysql root password><br />
<br />
You should see something very similar to<br />
<br />
Welcome to the MySQL monitor. Commands end with ; or \g.<br />
Your MySQL connection id is 33<br />
Server version: 5.0.75-0ubuntu10.2 (Ubuntu)<br />
<br />
Type 'help;' or '\h' for help. Type '\c' to clear the buffer.<br />
<br />
<br />
Enter <code>exit</code> to exit<br />
<br />
mysql> exit<br />
Bye<br />
$<br />
<br />
== Reboot and Test ==<br />
<br />
Now reboot the system (click on your name in the upper right hand corner, then select <code>Restart</code>).<br />
<br />
Now connect to<br />
"http://localhost/" using a browser on your machine and/or to your<br />
server from a browser on a remote machine. You should see the page '''It Works''' indicating that Apache is running.<br />
<br />
This is also a good time to check that 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 <code>Keyboard Interactive</code> to the list of "Authentication methods" under "Authentication" if it's not already there. <br />
<br />
Finally test that MySQL is running.<br />
<br />
$ mysql -u root -p <br />
Enter Password: <mysql root password><br />
...<br />
mysql><br />
<br />
Now lets check the MySQL users.<br />
There are three root accounts, one is <code>root@localhost</code>, one is <code>root@127.0.0.1</code> and the third is <code>root@host_name</code> where <code>host_name</code> is the name of your server. To find see name, do the following <br />
<br />
mysql> SELECT Host, User, Password FROM mysql.user;<br />
<br />
You will see a table with four users (three <code>root</code> and one <code>debian-sys-maint</code>). <br />
You should see that all four users now have passwords (which will be displayed in encrypted form).<br />
<br />
Now exit MySQL<br />
<br />
mysql> exit<br />
Bye<br />
$<br />
<br />
<br />
<br />
Congratulate yourself. You are now ready for the next and hopefully easy part, installing WeBWorK.<br />
<br />
== Downloading the WeBWorK System Software and Problem Libraries ==<br />
We are finally at the point where we can start downloading and installing WeBWorK. We will use CVS to download WeBWorK. This is easy and it will also make it easy to update the system in the future. Note that the following are rather long commands; it is much easier to copy (<code>^C</code>) them from this document and paste (<code>&lt;Shift&gt; &lt;Ctrl&gt; &lt;V&gt;</code>) them in a terminal window<br />
<br />
$ cd<br />
$ cd downloads<br />
<br />
$ cvs -d :pserver:anoncvs@cvs.webwork.rochester.edu:/webwork/cvs/system checkout -r rel-2-4-patches webwork2 pg<br />
$ cvs -d :pserver:anoncvs@cvs.webwork.rochester.edu:/webwork/cvs/npl checkout NationalProblemLibrary<br />
<br />
The first download gives you the latest released version with patches.<br />
The second download contains the WeBWorK National Problem Library. This now includes the Rochester and Union Libraries along with others as sub libraries. Your system will be loaded with many thousands of WeBWorK problems (over 16,000 currently).<br />
<br />
== Installing WeBWorK ==<br />
=== Move the System into the Required Directories ===<br />
As <code>root</code> create a <code>webwork</code> directory under <code>/opt</code> and move directories there. <br />
<br />
$ su<br />
<root password><br />
# mkdir /opt/webwork<br />
# mv webwork2 /opt/webwork/<br />
# mv pg /opt/webwork/<br />
<br />
Now create the <code>courses</code> and <code>libraries</code> directories under <code>webwork</code> and copy and move content there.<br />
<br />
# mkdir /opt/webwork/courses<br />
# mkdir /opt/webwork/libraries<br />
# mv NationalProblemLibrary /opt/webwork/libraries/<br />
# cd /opt/webwork/webwork2/courses.dist<br />
# cp *.lst /opt/webwork/courses/<br />
# cp -r modelCourse/ /opt/webwork/courses/<br />
<br />
=== Setting Permissions ===<br />
<br />
The PG installation directory and files should be owned by root and not writable by other users:<br />
<br />
# cd /opt/webwork/pg<br />
# chown -R root:root .<br />
# chmod -R u+rwX,go+rX .<br />
<br />
Most WeBWorK directories and files should also be owned by root and not writable by other users:<br />
<br />
# cd /opt/webwork/webwork2<br />
# chown -R root:root .<br />
# chmod -R u+rwX,go+rX .<br />
<br />
Certain data directories need to be writable by the web server. These are <code>DATA</code>, <code>courses</code>, <code>htdocs/tmp</code>, <code>logs</code>, and <code>tmp</code>. It is convenient to give WeBWorK administrators access to these directories as well, so they can perform administrative tasks such as removing temporary files, creating and editing courses from the command line, managing logs, and so on. We will create a new group called <code>wwdata</code>, containing both the WeBWorK administrators and the web server.<br />
<br />
# Select <code>System</code>, <code>Administration</code> and then <code>Users and Groups</code><br />
# Click on <code>Unlock</code><br />
# Enter <code>&lt;your password&gt;</code> and click <code>Authenticate</code><br />
# Select <code>Manage Groups</code><br />
# Click <code>Add Group</code> <br />
# For <code>Group name</code> enter <code>wwdata</code><br />
# Under <code>Group Members</code> select yourself and click <code>OK</code><br />
# Click <code>Close</code><br />
<br />
If there are other users who will also be administering WeBWorK files,<br />
now is a good time to add them. And remember to add them to the <code>wwdata</code> group as above. When finished<br />
# Click <code>Close</code> again<br />
<br />
Because system users are not shown by default, we can not simply use the <code>Group Manager</code> to add the Apache2 webserver (which runs as <code>www-data</code>) to the <code>wwdata</code><br />
group so we will do this by hand.<br />
<br />
# cd /etc<br />
# cp group group.bak1<br />
# gedit group<br />
<br />
<br />
# In the gedit window scroll to the last line. <br />
# It should look like <code>wwdata:x:1001:<your userid></code><br />
# Append to this line <code>,www-data</code><br />
# Then Save and Quit<br />
<br />
<br />
<br />
You can check that this succeeded in a terminal window by entering<br />
<br />
# exit<br />
$ id <your userid><br />
<br />
and then you should see <code>wwdata</code> listed under groups. Also<br />
<br />
$ id www-data<br />
<br />
should show wwdata listed under groups. Now we make the WeBWorK directories that need to be writable by the web server have <code>wwdata</code> as their group. The following are rather long commands; you might want to copy them and paste them into your terminal window rather than typing them.<br />
<br />
$ su<br />
<root password><br />
# cd /opt/webwork/webwork2/<br />
# chgrp -R wwdata DATA ../courses htdocs/tmp logs tmp<br />
# chmod -R g+w DATA ../courses htdocs/tmp logs tmp<br />
# find DATA/ ../courses/ htdocs/tmp logs/ tmp/ -type d -a ! -name CVS -exec chmod g+s {} \;<br />
# exit<br />
$<br />
<br />
== Configuring the Shell ==<br />
<br />
To make working with WeBWorK easier, there are a couple of changes you can make to your shell environment.<br />
<br />
Add the WeBWorK <code>bin</code> directory to your path. This will allow you to run WeBWorK command-line utilities without typing the full path to the utility. Goto your home directory and backup your <code>.bashrc</code> file<br />
<br />
$ cd<br />
$ cp .bashrc .bashrc.bak1<br />
<br />
Now edit <code>.bashrc</code><br />
<br />
$ gedit .bashrc<br />
<br />
After the last line add the two lines:<br />
<br />
export PATH=$PATH:/opt/webwork/webwork2/bin<br />
export WEBWORK_ROOT=/opt/webwork/webwork2<br />
<br />
Then save the file and Quit.<br />
<br />
Close your Terminal Window and open a new one so the above changes<br />
take effect. You can check that they have by<br />
<br />
$ echo $PATH<br />
$ echo $WEBWORK_ROOT<br />
<br />
== Checking Module Dependancies ==<br />
<br />
<br />
<br />
WeBWorK includes a script called <code>check_modules.pl</code> that verifies that the needed programs and Perl modules are installed on your system. Run this script to make sure you have installed the required programs and Perl modules.<br />
<br />
$ check_modules.pl apache2<br />
<br />
Scroll up and look through the listing. It should find everything except <code>PHP::Serialization</code>, <code>SOAP::Lite</code>, <code>MIME::Parser</code> and <code>XMLRPC::Lite</code> which are only required if you plan to use WeBWorK with Moodle and <code>tth</code> which is a deprecated display mode. If something is missing (flagged by <code>**</code>), 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.<br />
<br />
== Configuring WeBWorK ==<br />
<br />
=== Making Copies of the Distribution Configuration Files ===<br />
<br />
Before configuring the system, you must make local copies of the <code>global.conf</code> and <code>database.conf</code> configuration files, located in <code>/opt/webwork/webwork2/conf/</code> . Since these are owned by <code>root</code><br />
<br />
$ su<br />
<root password><br />
# cd /opt/webwork/webwork2/conf<br />
# cp global.conf.dist global.conf<br />
# cp database.conf.dist database.conf<br />
<br />
=== Global Configuration ===<br />
<br />
Most WeBWorK configuration is done in the file <code>/opt/webwork2/conf/global.conf</code>. This file provides system-wide configuration settings, and defaults for course settings. Any setting in this file can be overridden in the <code>course.conf</code> file for a particular course. To override a setting for a course, just put the new setting (using the same syntax as is in <code>global.conf</code>) in the <code>course.conf</code> file.<br />
<br />
There are several options that must be set for WeBWorK to work with your system. The rest of the file consists of customization options. Now edit <code>global.conf</code><br />
<br />
# cd /opt/webwork/webwork2/conf<br />
# gedit global.conf<br />
<br />
WeBWorK uses the DateTime module. DateTime is supposed to be able to determine the local timezone itself without you having to enter it but this often fails so it is best to just set it here. For is a list of timezones recognized by DateTime go to<br />
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 <code>DateTime::TimeZone::America::New_York</code> and you should replace <code>$siteDefaults{timezone} = "";</code> by <code>$siteDefaults{timezone} = "America/New_York";</code> <br />
<br />
# Search for <code>$siteDefaults{timezone} = "";</code> and enter your local timezone.<br />
<br />
At this point <code>TtH</code> is a deprecated display mode which we didn't install so we have to remove it from the list of possible display modes. <br />
<br />
# Search for <code>formattedText</code> and comment out the line <code>"formattedText", # format math expressions using TtH</code><br />
so it becomes<br />
<br />
# "formattedText", # format math expressions using TtH<br />
<br />
We need to set a password that WeBWorK uses when it communicates with the MySQL database. Note that this is not the same as the <code>&lt;mysql root password&gt;</code> which is the password the MySQL root user uses.<br />
# Search for <code>$database_password = "";</code> and replace this by <br /> <code>$database_password = "database_password";</code> <br />
where of course you should replace 'database_password' with your own password. Remember this password as we will need it below.<br />
<br />
WeBWorK sends mail in three instances. The PG system sends mail to report answers to questionnaires and free-response problems. The mail merge module is used to send mail to course participants, i.e. to report scores. The feedback module allows participants to send mail to course instructors.<br />
<br />
To send mail, WeBWorK needs the address of an SMTP server. Normally you will use the address of your school's SMTP server. If the local machine is running an SMTP server, use <code>localhost</code>. IMPORTANT: Our instructions above did not install an SMTP server so you will have to install and configue one if you do not use your school's SMTP server. When connecting to the SMTP server, WeBWorK must also send an email address representing the sender of the email (this has nothing to do with the <code>From</code> address on the mail message). Edit the lines<br />
$mail{smtpServer} = 'mail.yourschool.edu'; <br />
$mail{smtpSender} = 'webwork@yourserver.yourschool.edu';<br />
<br />
entering the appropriate information.<br />
<br />
If you want WeBWorK questionnaires or similar things from different courses to be mailed to a central person or persons (e.g. the WeBWorK administrator), edit the lines<br />
<br />
$mail{allowedRecipients} = [<br />
#'prof1@yourserver.yourdomain.edu',<br />
#'prof2@yourserver.yourdomain.edu',<br />
];<br />
<br />
appropriately removing the <code>#</code> and using the professor(s) actual email address(es). In order to have professors from individual courses receive such email, this <br />
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 global.conf, so if in addition you want e.g. the WeBWorK administrators to receive copies, you have to add them as well.<br />
<br />
Then save the file and Quit.<br />
<br />
<br />
Now become a regular user again<br />
<br />
# exit<br />
$<br />
<br />
WeBWorK uses a single database, called <code>webwork</code>, for all courses. We will create the <code>webwork</code> database now.<br />
<br />
To do this do the following (before you just copy, paste and hit <code>&lt;Enter&gt;</code> notice that you have to replace <code>database_password</code> with the password you set when editing <code>global.conf</code> above):<br />
<br />
$ mysql -u root -p mysql<br />
Enter password: <mysql root password><br />
mysql> CREATE DATABASE webwork;<br />
mysql> GRANT SELECT, INSERT, UPDATE, DELETE, CREATE, ALTER, DROP, LOCK TABLES ON webwork.* TO webworkWrite@localhost IDENTIFIED BY 'database_password';<br />
mysql> exit<br />
Bye<br />
$ <br />
<br />
where as we said replace <code>database_password</code> with the password you set when editing <code>global.conf</code> above.<br />
<br />
Since version 2.3.0 WeBWorK has an automatic database upgrade system. Rather than manually issuing SQL commands to make changes to the database, or using ad-hoc scripts like wwdb_addgw, there is a single script called <code>wwdb_upgrade</code> that applies any necessary updates. It should be run when creating a new database, and any time you upgrade WeBWorK.<br />
<br />
$ /opt/webwork/webwork2/bin/wwdb_upgrade -v<br />
<br />
You should see<br />
<br />
...<br />
Database is up-to-date at version 23.<br />
...<br />
<br />
=== jsMath Settings ===<br />
<br />
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 <code>webwork2/htdocs/jsMath/jsMath-fonts.tar.gz</code>, and you need to unpack this tarball before jsMath will work properly. Use the command<br />
<br />
$ su<br />
<root password><br />
# cd /opt/webwork/webwork2/htdocs/jsMath<br />
# tar vfxz jsMath-fonts.tar.gz<br />
<br />
This will unpack the archive. Since there are 20,000 tiny files, it can take a little while, so the <code>v</code> 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.<br />
<br />
<br />
== Configuring Apache ==<br />
WeBWorK ships with an Apache config file that needs to linked into your Apache configuration process. The file is named <code>webwork.apache2-config.dist</code> and located in the <code>conf</code> directory. First, copy the file to <code>webwork.apache2-config</code>:<br />
<br />
# cd /opt/webwork/webwork2/conf<br />
# cp webwork.apache2-config.dist webwork.apache2-config<br />
<br />
and now link it into your Apache configuration process<br />
<br />
# cd /etc/apache2/conf.d<br />
# ln -s /opt/webwork/webwork2/conf/webwork.apache2-config webwork.conf<br />
<br />
Next we will make a few changes to Apache's default configuration. First we backup the configuration file<br />
<br />
# cd /etc/apache2/<br />
# cp apache2.conf apache2.conf.bak1<br />
# gedit apache2.conf<br />
<br />
Search for the line<br />
Timeout 300<br />
and replace it by<br />
Timeout 1200<br />
Next seach for the lines<br />
MaxClients 150<br />
MaxRequestsPerChild 0<br />
Which occur under <code><IfModule mpm_prefork_module></code> and replace them by<br />
# For WeBWorK a rough rule of thumb is 20 MaxClients per 1 GB of memory<br />
MaxClients 20<br />
MaxRequestsPerChild 100<br />
where you should set <code>MaxClients</code> depending on the amount of memory your server has using the above rule of thumb.<br />
<br />
Then save the file and quit.<br />
<br />
Finally we copy WeBWorK's icon file <code>favicon.ico</code> to Apache's <code>www</code> directory.<br />
# cp /opt/webwork/webwork2/htdocs/favicon.ico /var/www<br />
<br />
Now restart Apache <br />
<br />
# apache2ctl graceful<br />
# exit<br />
$<br />
<br />
== Test your configuration ==<br />
<br />
# Test the <code>/webwork2</code> location by visiting <code>http://yourserver.yourschool.edu/webwork2</code>. You should see the WeBWorK home page with no courses listed. Actually the directory <code>/opt/webwork/courses/</code> does contain the <code>modelCourse</code> but the <code>modelCourse</code> is not a real course so you will get an error message if you try to log into it. It will be used a as model for setting up other courses. For this reason <code>/opt/webwork/courses/modelCourse/</code> contains a file named <code>hide_directory</code> and so the <code>modelCourse</code> is not visible.<br />
# Test the <code>/webwork2_files</code> location by visiting <code>http://yourserver.yourschool.edu/webwork2_files</code>. You should see the "WeBWorK Placeholder Page".<br />
# You cannot test the <code>/webwork2_course_files</code> location until you have created a course.<br />
<br />
==If Something is Wrong ==<br />
If something is wrong one of the first things to check is that the config files have been edited correctly (e.g. one time a wrapped line in <code>global.conf</code> caused me problems, another time it was a missing single quote). A quick way to check this is to do a <code>diff</code> between the edited and distributed versions and check that <code>diff</code> reports the changes you made and only those.<br />
<br />
# exit<br />
$<br />
$ cd /etc/apache2/<br />
$ diff apache2.conf apache2.conf.bak1<br />
$ cd /opt/webwork/webwork2/conf/<br />
$ diff global.conf global.conf.dist<br />
$ diff database.conf database.conf.dist<br />
$ diff webwork.apache2-config webwork.apache2-config.dist <br />
<br />
If something is wrong and you fix it, you will have to restart Apache for the changes to take effect<br />
<br />
$ su<br />
<root password><br />
# apache2ctl graceful<br />
# exit<br />
$<br />
<br />
== Create the admin Course ==<br />
<br />
[[Course Administration]] gives information about creating courses. Here we will give explicit instructions for doing this.<br />
<br />
$ su<br />
<root password><br />
# newgrp wwdata<br />
# umask 2<br />
# cd /opt/webwork/courses<br />
# /opt/webwork/webwork2/bin/addcourse admin --db-layout=sql_single --users=adminClasslist.lst --professors=admin<br />
# exit<br />
# exit<br />
$<br />
<br />
Now goto <code>http://yourserver.yourschool.edu/webwork2</code> and should see the WeBWorK home page with <code>Course Adninistration</code> listed at the top. Click on it and login with Username <code>admin</code> and Password <code>admin</code> . This first thing you should do is register your new WeBWorK installation. It's quick and easy, just click on <code>Register</code>. The next thing you should do is click on <code>Password/Email</code> and change <code>admin</code> 's password to something more secure than <code>admin</code> . <br />
<br />
Unless you choose oherwise, users with <code>professor</code> privilges in the <code>admin</code> course (i.e. WeBWorK administrators) will automatically be added to new courses with <code>professor</code> privilges and the same password as in the <code>admin</code> course. Initially the only such user is <code>admin</code> (hopefully you are not confused by the fact that the course <code>admin</code> has a user named <code>admin</code>). It's usually convenient make yourself a WeBWorK administrator. To do this (assuming you are logged in as <code>admin</code> to the <code>admin</code> course at <code>http://yourserver.yourschool.edu/webwork2/admin</code> )<br />
# Click on <code>Classlist Editor</code> in the left panel<br />
# Check <code>Add 1 student(s)</code> and click <code>Take Action!</code><br />
# Enter the appropiate information (you can leave the last three items blank) and click <code>Add Students</code><br />
# Click on <code>Classlist Editor</code> in the left panel again<br />
<br />
# When you enter a new student, by default their <code>Student ID</code> is used as their password. We'll change this now.<br />
# Select yourself with a check mark and then check <code>Give new password to Selected users</code> or just check <code>Give new password to All users</code> (as a safely mechanism you can not change the password for the user you are logged in as, currently <code>admin</code>, this way) and then click <code>Take Action!</code><br />
# Enter the password, check <code>Save changes</code> and then click <code>Take Action!</code><br />
# Finally give yourself <code>professor</code> privilges by selecting yourself with a check mark, checking <code>Edit Selected users</code> and then clicking <code>Take Action!</code> (or by just clicking on the "pencil" next to your login name which is a much faster way to edit classlist data for a single user)<br />
# Now at the far right change <code>Permission Level</code> from <code>student</code> to <code>professor</code><br />
# Check <code>Save changes</code> and then click <code>Take Action!</code><br />
<br />
At some point you will probably want to hide the <code>admin</code> course so that it is not listed on the WeBWorK home page. As we noted above the <code>modelCourse</code>, which is already hidden, is not a real course so you will get an error message if you try to log into it. This is a good reason to hide it. The <code>modelCourse</code> is very useful as a model (hence its name) for setting up other courses. The <code>admin</code> course is used for administering WeBWorK and even though regular users can not log into it (you did change the <code>admin</code> password, didn't you!!), it a little bit cleaner and safer to hide it from prying eyes. <br />
To hide a course place a file named <code>hide_directory</code> in the course directory and it will not show up in the courses list on the WeBWorK home page. It will still appear in the Course Administration listing. If you do this you will still be able to access the <code>admin</code> course using the URL <code>http://yourserver.yourschool.edu/webwork2/admin</code> but you will not see a link for it on the WeBWorK home page <code>http://yourserver.yourschool.edu/webwork2</code> . Let's hide the <code>admin</code> course.<br />
<br />
$ sudo cp /opt/webwork/courses/modelCourse/hide_directory /opt/webwork/courses/admin<br />
password:<your password><br />
<br />
<br />
Now goto <code>http://yourserver.yourschool.edu/webwork2</code> and no course will be listed.<br />
<br />
== Starting and Stopping Apache, MySQL and the GNOME desktop GUI ==<br />
If you make changes to the system, you will have to restart <code>apache2</code> before the changes take effect. On rare occasions you may need to restart <code>MySQL</code>. <br />
=== Starting and Stopping Apache ===<br />
You have to run these commands as <code>root</code>.<br />
<br />
To start or restart (i.e. stop and then start) the <code>apache2</code> webserver run the command <br />
$ sudo apache2ctl graceful<br />
password:<your password><br />
You can also start <code>apache2</code> by<br />
$ sudo apache2ctl start<br />
password:<your password><br />
and restart it with<br />
$ sudo apache2ctl restart<br />
password:<your password><br />
<code>restart</code> is less graceful but more powerful than <code>graceful</code>. Sometimes <code>graceful</code> fails to kill all <code>apache2</code> child processes.<br />
<br />
To stop the Apache webserver run the command <br />
<br />
$ sudo apache2ctl stop<br />
password:<your password><br />
<br />
You can also start or stop apache2, listed as <code>Web server (apache2)</code>, by using the GUI interface.<br />
# Select <code>System</code>, <code>Administration</code> and then <code>Services</code><br />
# Click on <code>Unlock</code><br />
# Enter <code>&lt;your password&gt;</code> and click <code>Authenticate</code><br />
# Scroll down to <code>Web server (apache2)</code><br />
# If <code>apache2</code> is running, uncheck its check box and click <code>Close</code> to stop it<br />
# If <code>apache2</code> is stopped, check its check box and click <code>Close</code> to start it<br />
<br />
Another method is to use the <code>init.d</code> script <code>apache2</code>. Run<br />
$ sudo /etc/init.d/apache2<br />
password:<your password><br />
and you will get a list of allowed commands (<code>start</code>, <code>stop</code>, <code>restart</code>, etc).<br />
<br />
Note that in an earlier version of Ubuntu I found using the GUI interface somewhat unreliable.<br />
<br />
=== Starting and Stopping MySQL ===<br />
You have to run these commands as <code>root</code>.<br />
<br />
To start the <code>MySQL</code> server run the command <br />
<br />
$ sudo /etc/init.d/mysql start<br />
password:<your password><br />
<br />
To stop the <code>MySQL</code> server run the command <br />
<br />
$ sudo /etc/init.d/mysql stop<br />
password: <your password><br />
<br />
To restart the <code>MySQL</code> server run the command <br />
<br />
$ sudo /etc/init.d/mysql restart<br />
password: <your password><br />
<br />
You can also start or stop MySQL, listed as <code>Database server (mysql)</code>, by using the GUI interface.<br />
<br />
# Select <code>Desktop</code>, <code>Administration</code> and then <code>Services</code><br />
# Click on <code>Unlock</code><br />
# Enter <code>&lt;your password&gt;</code> and click <code>Authenticate</code><br />
# Scroll down to <code>Database server (mysql)</code><br />
# If <code>mysql</code> is running, uncheck its check box and click <code>Close</code> to stop it<br />
# If <code>mysql</code> is stopped, check its check box and click <code>Close</code> to start it<br />
<br />
=== Starting and stopping the GNOME desktop GUI ===<br />
<br />
The GNOME desktop is automatically started when the system boots. <br />
<br />
To stop <code>GNOME</code> so that you only have a standard terminal window run the following in a standard terminal window<br />
<br />
$ sudo /etc/init.d/gdm stop <br />
password: <your password><br />
<br />
If you stopped <code>GNOME</code> and want to restart it run the following in a standard terminal window<br />
<br />
$ sudo /etc/init.d/gdm start <br />
password: <your password><br />
<br />
==Install the WeBWorK Problem Libraries ==<br />
Before we create a real course we will install the WeBWorK Problem Libraries.<br />
<br />
===Install the National Problem Library ===<br />
The <code>National Problem Library</code> consists of both WeBWorK problems and methods for searching and selecting problems. Also it contains as sub libraries many of the other standard libraries. We have to tell WeBWork where to find it.<br />
<br />
Edit <code>global.conf</code>.<br />
<br />
$ cd /opt/webwork/webwork2/conf<br />
$ su<br />
Password: <root password><br />
# gedit global.conf<br />
<br />
Search for <code>problemLibrary</code> and replace <code>$problemLibrary{root} = "";</code> by <br /> <code>$problemLibrary{root} = "/opt/webwork/libraries/NationalProblemLibrary";</code> <br />
<br />
Then save the file and quit. And return to a regular user<br />
<br />
#exit<br />
$<br />
<br />
Run the <code>NPL-update</code> script making sure you are in the <code>/opt/webwork/libraries/NationalProblemLibrary</code> directory. This directory contains the files <code>loadDB2</code> and <code>create_tables2.sql</code>.<br />
<br />
$ cd /opt/webwork/libraries/NationalProblemLibrary<br />
$ NPL-update<br />
<br />
This has to convert a lot of data (over 18000 files) so please be patient; it can take a long time.<br />
<br />
If at some time in the future you want to upgrade the Problem Library, the process<br />
is simpler. Optionally remove the previous copy of the<br />
library, unpack the new copy in the same place, and run NPL-update.<br />
<br />
Finally we put a link to the National Problem Library in the modelCourse so that when we create courses copying templates from the modelCourse, the NPL will be available.<br />
<br />
$ cd /opt/webwork/courses/modelCourse/templates/<br />
$ sudo ln -s /opt/webwork/libraries/NationalProblemLibrary Library<br />
password: <your password><br />
<br />
===Set up the Rochester and Union Libraries ===<br />
<br />
This step is optional. It creates buttons in the Library Browser which give direct links to the Rochester and Union libraries. If you don't do this, you can find these libraries and others under the <code>NPL Directory</code> button.<br />
<br />
First we need to edit <code>global.conf</code> one last time<br />
<br />
$ cd /opt/webwork/webwork2/conf<br />
$ su<br />
Password: <root password><br />
# gedit global.conf<br />
<br />
Search for <code>courseFiles{problibs}</code> and scroll down several lines to the lines<br />
# rochesterLibrary =&gt; "Rochester",<br />
# unionLibrary =&gt; "Union",<br />
Uncomment these lines (i.e. remove the <code>#</code>) so they become <br />
rochesterLibrary =&gt; "Rochester",<br />
unionLibrary =&gt; "Union",<br />
Then save the file and quit.<br />
<br />
We next put links to the Rochester and Union Libraries in the <code>modelCourse</code> so that when we create courses copying templates from the <code>modelCourse</code>, these libraries will be available. Skip this step if you usually only want to use 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 <code>NPL Directory</code> button in the Library Browser. This step simply creates buttons in the Library Browser so that you can access the Rochester and Union libraries directly.<br />
<br />
# exit<br />
$ cd /opt/webwork/courses/modelCourse/templates/<br />
$ sudo ln -s /opt/webwork/libraries/NationalProblemLibrary/Union unionLibrary<br />
password: <your password><br />
$ sudo ln -s /opt/webwork/libraries/NationalProblemLibrary/Rochester rochesterLibrary<br />
<br />
If you want to put another library into the <code>modelCourse</code>, just do the analogous thing. If you just want the additional library in a particular course, add the link in the <code>templates</code> directory of that course. If you look in the directory <code>/opt/webwork/libraries/NationalProblemLibrary/</code> you might find other libraries that are not yet listed in <code>global.conf</code> and these can be added in the same way as the <code>Rochester and </code><code>Union</code> libraries. Finally if you add a library with non standard symbols in the name (e.g. <code>uva-statLibrary</code>) you have to use single quotes when adding it to <code>global.conf</code>, e.g. <br><br />
&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp; <code>'uva-statLibrary' => "UVA-Stat",</code> <br><br />
It's easier to just avoid such names.<br />
<br />
===Install and Set Up the CAPA Library ===<br />
<br />
This step is optional. It installs and sets up [[CAPA Physics Problems|the CAPA Library]], which is a library of physics problems.<br />
<br />
First we download the CAPA Library including required macros.<br />
<br />
$ cd<br />
$ cd downloads<br />
$ cvs -d :pserver:anoncvs@cvs.webwork.rochester.edu:/webwork/cvs/rochester checkout rochester_physics_problib<br />
<br />
As <code>root</code> create a <code>CAPA</code> directory under <code>/opt/webwork</code> and move the CAPA macros there. Then move the CAPA graphics and library files to the required locations.<br />
<br />
$ su<br />
<root password><br />
# mkdir /opt/webwork/CAPA<br />
# cd rochester_physics_problib/macros/ <br />
# mv CAPA_Tools /opt/webwork/CAPA/ <br />
# mv CAPA_MCTools /opt/webwork/CAPA/ <br />
# cd .. <br />
# mv CAPA_Graphics /opt/webwork/webwork2/htdocs/ <br />
# cd .. <br />
# mv rochester_physics_problib /opt/webwork/libraries/ <br />
<br />
We need to edit <code>global.conf</code> again<br />
<br />
# cd /opt/webwork/webwork2/conf<br />
# gedit global.conf<br />
<br />
Search for <code>courseFiles{problibs}</code> and scroll down several lines to the line<br />
# capaLibrary => "CAPA",<br />
Uncomment this line (i.e. remove the <code>#</code>) so it becomes <br />
capaLibrary => "CAPA",<br />
<br />
Next search for the lines<br />
$pg{specialPGEnvironmentVars}{CAPA_Tools} = "$courseDirs{macros}/CAPA_Tools/", <br />
$pg{specialPGEnvironmentVars}{CAPA_MCTools} = "$courseDirs{macros}/CAPA_MCTools/", <br />
$pg{specialPGEnvironmentVars}{CAPA_GraphicsDirectory} = "$courseDirs{html}/CAPA_Graphics/", <br />
$pg{specialPGEnvironmentVars}{CAPA_Graphics_URL} = "$courseURLs{html}/CAPA_Graphics/", <br />
and edit them so that they read as follows (cut and paste is the best way to do this)<br />
<br />
$pg{specialPGEnvironmentVars}{CAPA_Tools} = "/opt/webwork/CAPA/CAPA_Tools/", <br />
$pg{specialPGEnvironmentVars}{CAPA_MCTools} = "/opt/webwork/CAPA/CAPA_MCTools/", <br />
$pg{specialPGEnvironmentVars}{CAPA_GraphicsDirectory} = "$webworkDirs{htdocs}/CAPA_Graphics/", <br />
$pg{specialPGEnvironmentVars}{CAPA_Graphics_URL} = "$webworkURLs{htdocs}/CAPA_Graphics/", <br />
<br />
Then save the file and quit. Note that we are setting up the CAPA macros and graphics so that they can be used by any WeBWorK course on the server.<br />
<br />
There is one final step that is needed. We have to put a link in the templates directory of every course that needs access to the CAPA Library. If you want to have every course you create have access to the CAPA Library (unlikely unless you are in a physics department) put the link in the <code>modelCourse</code><br />
<br />
$ cd /opt/webwork/courses/modelCourse/templates/<br />
sudo ln -s /opt/webwork/libraries/rochester_physics_problib/ capaLibrary<br />
password: <your password><br />
<br />
More likely you just want to do this for individual courses. We don't have any yet. But for example after creating <code>myTestCourse</code> below, to set up access to the CAPA Library from <code>myTestCourse</code>, do the following<br />
cd /opt/webwork/courses/myTestCourse/templates/<br />
sudo ln -s /opt/webwork/libraries/rochester_physics_problib/ capaLibrary<br />
and do the analogous thing for every course that needs access to the CAPA Library.<br />
Then to gain access to the CAPA Library from the course, simply go to the <code>Library Browser</code> and click on the <code>CAPA</code> button.<br />
<br />
==Create Your First Actual Course ==<br />
<br />
Since we have edited <code>global.conf</code> a lot and this is a very critical file, it would be a good idea to run<br />
$ cd /opt/webwork/webwork2/conf<br />
$ diff global.conf global.conf.dist<br />
<br />
and check that you haven't made any mistakes (e.g. by introducing an inadvertent line break, etc). If there are any mistakes, correct them. Remember that any time you change<br />
<code>global.conf</code>, you must restart the Apache webserver in order for these changes to take effect. <br />
<br />
Since we have edited <code>global.conf</code> extensively and haven't restartes Apache we do so now.<br />
$ sudo apache2ctl graceful<br />
password:<your password><br />
<br />
Now log into the <code>admin</code> course ( <code>http://yourserver.yourschool.edu/webwork2/admin</code> ) as yourself or <code>admin</code> and <br />
# click on <code>Add Course</code><br />
# For <code>Course ID</code> enter <code>myTestCourse</code><br />
# For <code>Course Title</code> enter <code>My Test Course</code><br />
# Enter your institution<br />
# Leave <code>Add WeBWorK administrators to new course</code> checked<br />
# Add an additional instructor if you wish<br />
# Copy templates from: <code>modelCourse</code> (the default action)<br />
# Select sql_single for the database layout (the default action)<br />
# Click on <code>Add Course</code><br />
# Click <code>Log into myTestCourse</code><br />
<br />
and log in either as <code>admin</code> or yourself.<br />
<br />
At some point you will probably want to "hide" <code>myTestCourse</code> from general view but you already know how to do that.<br />
<br />
==Test that Things are Working Properly ==<br />
<br />
We will test out a few important parts of WeBWorK. If you run into problems, you should look at the Apache error log which is located at <code>/var/log/apache2/error.log</code>.<br />
<br />
Click on <code>Hmwk Sets Editor</code> on the <code>Main Menu</code>. Then select (by clicking the circle button) <code>Import</code>, select <code>setDemo.def</code> from the <code>from</code> drop down list and select <code>all current users</code> from the <code>assigning this set to</code> drop down list. Then hit <code>Take Action!</code><br />
<br />
Now click on <code>Homework Sets</code> on the <code>Main Menu</code> and click on <code>Demo</code>. Then look at the problems. Mathematical equations should be typeset. If not, edit the file <code>Constants.pm</code> in the directory <code>/opt/webwork/webwork2/lib/WeBWorK</code>. Change the line <code>$WeBWorK::PG::ImageGenerator::PreserveTempFiles = 0;</code> to <code>...::PreserveTempFiles = 1;</code>. Then restart Apache and view the first couple problems or some new ones. Then look in the directory <code>/opt/webwork/webwork2/tmp/</code>. <code>cd</code> to one of the <code>ImageGenerator.../tmp/</code> directories and look at the error and log files there. When you fix the problem remember to edit <code>...::PreserveTempFiles = 1;</code> back to 0 and restart Apache or you will be saving a lot of unnecessary files. Another useful trick is to try downloading a hard copy of an assignment and then (assuming there are errors) looking at the various log files that are linked to on the output page.<br />
<br />
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 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). <br />
<br />
Next click on <code>Prob. List</code> to bring back the Problem List Page and click on <code>Download a hardcopy of this homework set</code>. The page is a little complicated because you are a professor but you can just scroll to the bottom and click on <code>Generate hardcopy for selected users and selected sets</code>. You will get an error (because of the bad Problem 6) but just click <code>Download Hardcopy</code> to get what was generated. Also you can see links to various <br />
informational files that are available if you run into problems (normally these files are removed if there are no errors).<br />
<br />
Another thing to do is to use <code>Email</code> on the <code>Main Menu</code>. Again this page is a little complicated because you can do a lot of things with it (including mail merge) but at this point just select yourself in the list to the right and hit <code>Send Email</code> at the bottom. You should receive two emails. One is the message you just sent and the other is an email with subject "WeBWorK email sent" giving information on your mailing. <br />
<br />
As a final test click on <code>Library Browser</code> on the <code>Main Menu</code>. Click <code>Problem Library </code><br />
and select a <code>Subject</code>, <code>Chapter</code> and <code>Section</code> and then hit <code>View Problems</code>. The first 20 of your selected problems will be displayed. You can also test that you can access any additional Problem Libraries that you installed.<br />
<br />
If all the above tests work, you can be pretty confident that WeBWorK is working properly.<br />
<br />
Go back to <code>Hmwk Sets Editor</code> on the <code>Main Menu</code>. Then select (by clicking the circle button) <code>Import</code>, select <code>setOrientation.def</code> from the <code>from</code> drop down list and select <code>all current users</code> from the <code>assigning this set to</code> drop down list. Then hit <code>Take Action!</code>. Then go through the Orientation problems. This is a good first set to use for introducing students to WeBWorK.<br />
<br />
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.<br />
Click on <code>Classlist Editor</code> on the <code>Main Menu</code>.<br />
Then select (by clicking the circle button) <code>Add 1 student(s)</code>and hit <code>Take Action!</code>. Add one student, say Jane Smith, with <code>Student ID</code> <code>1234</code> and <code>Login Name</code> <code>jsmith</code>.<br />
Jane Smith's initial password will be her <code>Student ID</code> <code>1234</code>. Now login as Jane Smith and play around a little.<br />
<br />
==Optional Configurations==<br />
'''Optional A''' stores WeBWorK's "temporary" files in a separate partition. <br />
'''Optional B''' installs and configures a lightweight webserver to serve static files.<br />
'''Optional C''' configures Apache so that access to WeBWorK will be through SSL.<br />
<br />
===Implement Optional A (wwtmp)===<br />
<br />
Now is the time to implement '''Optional A''' if you choose to do so. Actually you can do this at any time and your active courses will continue to function seemingly without change. The only change behind the scenes will be that temporary files will be stored in a different location.<br />
<br />
First we set the group and permissions for the <code>wwtmp</code> directory<br />
<br />
$ su<br />
<root password><br />
# cd /var/www<br />
# chgrp wwdata wwtmp<br />
# chmod ug+w wwtmp<br />
# chmod g+s wwtmp<br />
<br />
Next we have to edit <code>global.conf</code> so that WeBWorK uses the new <code>wwtmp</code> directory. Since we have a working WeBWorK system, first we make a backup copy of <code>global.conf</code>.<br />
<br />
<br />
# cd /opt/webwork/webwork2/conf<br />
# cp global.conf global.conf.bak1<br />
# gedit global.conf<br />
<br />
Now edit <code>global.conf</code>. Find the lines <br />
<br />
$webworkDirs{htdocs_temp} = "$webworkDirs{htdocs}/tmp";<br />
$webworkURLs{htdocs_temp} = "$webworkURLs{htdocs}/tmp";<br />
and replace them by <br />
#$webworkDirs{htdocs_temp} = "$webworkDirs{htdocs}/tmp";<br />
#$webworkURLs{htdocs_temp} = "$webworkURLs{htdocs}/tmp";<br />
$webworkDirs{htdocs_temp} = '/var/www/wwtmp';<br />
$webworkURLs{htdocs_temp} = '/wwtmp';<br />
<br />
Next find the lines <br />
<br />
$courseDirs{html_temp} = "$courseDirs{html}/tmp";<br />
$courseURLs{html_temp} = "$courseURLs{html}/tmp";<br />
and replace them by <br />
#$courseDirs{html_temp} = "$courseDirs{html}/tmp";<br />
#$courseURLs{html_temp} = "$courseURLs{html}/tmp";<br />
$courseDirs{html_temp} = "/var/www/wwtmp/$courseName";<br />
$courseURLs{html_temp} = "/wwtmp/$courseName";<br />
<br />
Then save the file and quit. If you look at the <code>wwtmp</code> directory you will find it empty but after you restart apache and then access some WeBWorK problems, you will find temporary directories and files in <code>wwtmp</code>. Remember your have to restart apache for these changes to take effect.<br />
<br />
===Implement Optional B (lighttpd)===<br />
<br />
As is the case for '''Optional A''' you can implement '''Optional B''' at any time and your active courses will continue to function seemingly without change. The only change behind the scenes will be that static images and pages will be served by a light weight web server.<br />
<br />
First we install the light weight webserver <code>lighttpd</code><br />
<br />
# Open the <code>Synaptic Package Manager</code> (select <code>System</code>, <code>Administration</code>, <code>Synaptic Package Manager</code>). <br />
# Select <code>Search</code> <br />
# Search for <code>lighttpd</code> and select it<br />
# In the pop up window <code>Mark additional required changes?</code> click <code>Mark</code> to accept the requirements.<br />
# Now click <code>Apply</code> and <code>Apply</code> again to confirm the changes.<br />
<br />
You can now quit the <code>Synaptic Package Manager</code>.<br />
<br />
Now we configure <code>lighttpd</code>. First let's make a backup of the configuration file.<br />
<br />
<br />
$ su<br />
<root password><br />
# cd /etc/lighttpd<br />
# cp lighttpd.conf lighttpd.conf.bak1<br />
<br />
Now edit <code>lighttpd.conf</code>. <br />
<br />
# gedit lighttpd.conf<br />
<br />
Uncomment the line<br />
# "mod_status",<br />
so it becomes<br />
"mod_status",<br />
<br />
<br />
Apache2 is listening on port 80 so we set lighttp to listen on port 81. Find the line<br />
# server.port = 81<br />
and uncomment it <br />
server.port = 81<br />
<br />
Finally uncomment the line<br />
# status.status-url = "/server-status"<br />
so it becomes<br />
status.status-url = "/server-status"<br />
Then save the file and quit.<br />
<br />
Now restart lighttp<br />
<br />
$su<br />
<root password><br />
# /etc/init.d/lighttpd restart<br />
# exit<br />
$<br />
<br />
Note that you can just run <code>/etc/init.d/lighttpd</code> to get a list of all options.<br />
<br />
Now test your server by connecting to<br />
"http://localhost:81/" and/or connecting to your<br />
server from a browser on a remote machine. You should see the page '''It works!''' indicating that lighttp is running.<br />
<br />
You can check lighttp's status by connecting to<br />
"http://localhost:81/server-status" using a browser on your machine or from to "http://yourserver.yourschool.edu:81/server-status" from a browser on a remote machine.<br />
<br />
The Server-Status page doesn't indicate that lighttp is the web server, but it's certainly different than apache's Server-Status page "http://localhost/server-status".<br />
<br />
Next we configure WeBWorK to take advantage of lighttp.<br />
<br />
First let's make a backup copy of <code>global.conf</code> so that we can easily back out of these changes if necessary.<br />
<br />
# cd /opt/webwork/webwork2/conf<br />
# cp global.conf global.conf.bak2<br />
<br />
<br />
Now edit <code>global.conf</code>. Note that while '''Optional B''' is independent of '''Optional A''', we assume most people implementing '''Optional B''' will have already implemented '''Optional A'''. Therefore we give instructions for editing <br />
global.conf assuming that '''Optional A''' has been implemented. If this is not the case, modify the instructions below accordingly. Also replace <code>yourserver.yourschool.edu</code> with the correct address.<br />
<br />
# gedit global.conf<br />
<br />
Find the line<br />
$webworkURLs{htdocs_temp} = '/wwtmp'<br />
and replace it by<br />
#$webworkURLs{htdocs_temp} = '/wwtmp';<br />
$webworkURLs{htdocs_temp} = 'http://yourserver.yourschool.edu:81/wwtmp';<br />
<br />
Find the line<br />
$courseURLs{html_temp} = "/wwtmp/$courseName";<br />
and replace it by<br />
#$courseURLs{html_temp} = "/wwtmp/$courseName";<br />
$courseURLs{html_temp} = "http://yourserver.yourschool.edu:81/wwtmp/$courseName";<br />
<br />
Then save the file and quit.<br />
<br />
Now restart apache and lighttp.<br />
<br />
$ sudo apache2ctl graceful<br />
password:<your password><br />
$ sudo /etc/init.d/lighttpd restart<br />
<br />
To test things go to your test course <code>http://yourserver.yourschool.edu/webwork2/myTestCourse/</code>. Before you login right click on the WeBWorK icon in the upper left hand corner of the login page. The click on Properties (or whatever is appropriate on your browser) and check that the image is being served from port 81 (something like <code>http://yourserver.yourschool.edu:81/webwork2_files/images/webwork_rectangle.png</code>. Then log into your course and view a problem with typeset equations (e.g. Problem 1 of the Demo set). Again right click on the typeset equation and check that the image is being served from port 81.<br />
<br />
===Implement Optional C (SSL)===<br />
'''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.<br />
<br />
I cribbed these directions from several sources, the main one being http://www.akadia.com/services/ssh_test_certificate.html.<br />
<br />
We will create and work in a <code>tmp</code> directory.<br />
<br />
$ cd<br />
$ mkdir tmp<br />
$ cd tmp<br />
<br />
First we create an RSA Private Key.<br />
<br />
$ openssl genrsa -des3 -out server.key 1024<br />
<br />
When you are asked for a <code>pass phrase</code>, enter a phrase which we refer to as <code>&lt;my pass phrase&gt;</code> and then confirm it. Next generate a Certificate Signing Request<br />
$ openssl req -new -key server.key -out server.csr<br />
<br />
Enter the requested information. '''Important:''' when you are prompted for the <code>Common Name</code> enter your server's fully qualified domain name, something like <code>yourserver.yourschool.edu</code>. You can leave the last two items <br />
A challenge password []:<br />
An optional company name []:<br />
blank.<br />
<br />
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.<br />
<br />
$ cp server.key server.key.bak1<br />
$ openssl rsa -in server.key.bak1 -out server.key<br />
<br />
Next we generate a self-signed certificate which is good for 365 days<br />
<br />
$ openssl x509 -req -days 365 -in server.csr -signkey server.key -out server.crt<br />
<br />
Now we become root, move these files, and set their group and permission.<br />
<br />
$ su<br />
<root password><br />
# mv server.crt /etc/ssl/private<br />
# mv server.key /etc/ssl/private<br />
# cd /etc/ssl/private<br />
# chgrp ssl-cert server.*<br />
# chmod 640 server.*<br />
<br />
Next we enable the <code>mod_ssl</code> module<br />
# a2enmod ssl<br />
<br />
Now we have to configure Apache to use SSL.<br />
# cd /etc/apache2/sites-available/<br />
# cp default default.bak1<br />
# gedit default<br />
<br />
Replace the first line<br />
NameVirtualHost *<br />
by the two lines<br />
NameVirtualHost *:80<br />
NameVirtualHost *:443<br />
Now edit the next non blank line<br />
<VirtualHost *><br />
changing it to<br />
<VirtualHost *:80><br />
Next copy the entire section <br />
<VirtualHost *:80> <br />
...<br />
</VirtualHost><br />
(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.<br />
Edit the new second<br />
<VirtualHost *:80><br />
changing it to<br />
<VirtualHost *:443><br />
Now at the end of the file just above the line<br />
</VirtualHost><br />
add the three lines<br />
SSLEngine on<br />
SSLCertificateFile /etc/ssl/private/server.crt<br />
SSLCertificateKeyFile /etc/ssl/private/server.key<br />
Then save the file and quit.<br />
Finally we restart Apache<br />
# apache2ctl graceful<br />
and test things. Connect to https://yourserver.yourschool.edu/webwork2/mtTestCourse<br />
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). <br />
<br />
Assuming that everything is working, the last thing we do is set things up so that requests to http://yourserver.yourschool.edu/webwork2/ are automatically redirected to https://yourserver.yourschool.edu/webwork2/.<br />
<br />
# gedit default<br />
<br />
In the <br />
<VirtualHost *:80><br />
section just above the line<br />
ScriptAlias /cgi-bin/ /usr/lib/cgi-bin/<br />
add the line<br />
Redirect permanent /webwork2 https://yourserver.yourschool.edu/webwork2<br />
where of course you should edit <code>yourserver.yourschool.edu</code> appropriately.<br />
Then save the file and quit.<br />
Restart Apache<br />
# apache2ctl graceful<br />
and try connecting to http://yourserver.yourschool.edu/webwork2/. The real connection should be through https://yourserver.yourschool.edu/webwork2/.<br />
<br />
==Updating WeBWorK files==<br />
<br />
If you want to update a single WeBWorK file, e.g. <code>/opt/webwork/webwork2/lib/WeBWorK/Utils/FilterRecords.pm</code> you can just do<br />
$ cd /opt/webwork/webwork2/lib/WeBWorK/Utils<br />
$ sudo cvs update FilterRecords.pm<br />
If you want to update all files in a directory and in all its subdirectories, run the command <br />
$ sudo cvs update <br />
form the directory.<br />
<br />
Note that cvs tries to patch the file on disk with any changes. Usually this works but sometimes it results in a file that will not compile. To avoid this do e.g. the following<br />
$ cd /opt/webwork/webwork2/lib/WeBWorK/Utils<br />
$ sudo mv FilterRecords.pm FilterRecords.pm.old<br />
$ sudo cvs update FilterRecords.pm<br />
Cvs will warn you that the file was lost and then download the new version. You can do a <code>diff</code> between the new and old versions to see what changes have been made. That way you have two files (new and old) and both will compile.<br />
<br />
If you want to update the whole WeBWorK system, I would suggest doing the following.<br />
$ cd /opt/webwork<br />
$ sudo mv webwork2 webwork2_old<br />
$ sudo mv pg pg_old<br />
and then install the new version of <code>webwork2</code> and <code>pg</code> following the directions above. That way you can recover you old system simply by moving the old versions back. You also will have an old copy of your configuration files that you probably want when you edit the new ones.<br />
<br />
==Where to go From Here ==<br />
<br />
You should play around with <code>myTestCourse</code> e.g. click on <code>Library Browser</code> and browse the <code>Problem Library</code> and also the <code>Rochester</code> and <code>Union</code> libraries.<br />
<br />
Look at http://webhost.math.rochester.edu/webworkdocs/docs/courseadmin/usingwebwork<br />
<br />
Read [[Course Administration]] for more information about creating courses.<br />
<br />
Consult [[Category:Administrators]] for other WeBWorK documentation for system administrators.<br />
<br />
-- Main.ArnoldPizer - 15 May 2008 <br /><br />
<br />
[[Category:Installation Manuals]]</div>Xiong Chiamiovhttps://webwork.maa.org/mediawiki_new/index.php?title=Course_Administration&diff=1119Course Administration2009-08-17T20:22:01Z<p>Xiong Chiamiov: adding notes about courses with underscores in the name and shared prefixes</p>
<hr />
<div>This document details how to create and delete courses, import and export course databases, and perform other administrative functions.<br />
<br />
WeBWorK provides both command-line and web access to course administration tools.<br />
<br />
== The command-line utilities ==<br />
<br />
The command-line utilities, <code>addcourse</code>, <code>deletecourse</code>, and <code>wwdb</code>, provide access to administrative functions. To use them, you must have write access to the <code>courses</code> directory and any course directories you wish to modify. You must also set the <code>WEBWORK_ROOT</code> environment variable and you may add the WeBWorK <code>bin</code> directory to your path. See the [[Administrator's Guide/Installing WeBWorK|installation manual]] for more information.<br />
<br />
These utilities are useful for batch processing. For day-to-day administration, [[#The_web_interface|the web interface]] is more user friendly.<br />
<br />
=== Permissions issues ===<br />
<br />
In order to be useful, the web server running WeBWorK must have read and write access to all course files. When you create a course using the command-line tools, there is potential for those newly-created course files to be non-writeable by the web server.<br />
<br />
The easiest way to avoid permissions problems is to execute the command-line utilites as the same user the web server runs as. This is easily accomplised using the <code>su</code> or <code>sudo</code> commands. Assuming the web server runs as: <code>www-data</code>:<br />
<br />
sudo -u www-data addcourse ...<br />
<br />
Or, if sudo is not available:<br />
<br />
su www-data -c 'addcourse ...'<br />
<br />
If you do not have access to <code>su</code> or <code>sudo</code>, you can run these commands as yourself, as long as you have access to the course files. One way to do this is to make yourself a member of the web server's group. This gives you access to all the same files the web server has access to. You could instead create a new group called <code>wwdata</code>, containing both the WeBWorK administrators and the web server. See the [[Administrator's Guide/Installing WeBWorK|installation manual]] for more information.<br />
<br />
If you chose this method, switch to the web server's group (or the <code>wwdata</code> group) and change your file creation mask to allow group writeability before running the command-line utilities:<br />
<br />
newgrp www-data<br />
umask 2<br />
wwdb course1 export ...<br />
addcourse course2 ...<br />
wwdb course2 import ...<br />
...<br />
exit<br />
<br />
=== Creating courses on the command-line ===<br />
<br />
The <code>addcourse</code> utility is used to create courses.<br />
<br />
The simplest form of the command is:<br />
<br />
addcourse COURSEID<br />
<br />
However, you'll likely need to provide additional options.<br />
<br />
The <code>--db-layout=LAYOUT</code> option allows you to override the database layout set in <code>global.conf</code>.<br />
<br />
The <code>--users=FILE</code> option allows you to specify a classlist file from which users will be imported. The <code>--professors=USERID,[USERID...]</code> option allows you to denote one or more of the users in the file specified as professors. You should always make sure that at least one user is listed as a professor. Otherwise, you will not be able to edit your course.<br />
<br />
The <code>--templates-from=COURSEID</code> option causes the contents of the <code>templates</code> directory of another course to be copied to the new course. You can set up a "template" course with the problem source files, macro files, and mail merge forms desired and then use this feature to copy them to each new course you create. Please note that only the <code>templates</code> directory are copied, not the classlist or problem sets.<br />
<br />
Please note that course names with underscores in them can be an issue, if another course exists with the prefix of this one as its name. See [http://webwork.maa.org/moodle/mod/forum/discuss.php?d=6248 this thread] for more details.<br />
<br />
=== Deleting courses on the command-line ===<br />
<br />
The <code>delcourse</code> utility is used to delete courses.<br />
<br />
The simplest form of the command is:<br />
<br />
delcourse COURSEID<br />
<br />
Be very careful with this command: the course will be deleted immediately -- ''no questions asked!''<br />
<br />
<br />
=== Exporting a database on the command-line ===<br />
<br />
The <code>wwdb</code> utility is used to export course databases to an XML file.<br />
<br />
The simplest export command is:<br />
<br />
wwdb COURSEID export FILE<br />
<br />
where COURSEID is the name of the course to export from, and FILE is the file to export to. If FILE is =-=, the data will be printed on the standard output stream.<br />
<br />
You can additionally specify table names after FILE. If you do, only the data in those tables will be exported. For example, to export all user, password, and permission data from the course mth143:<br />
<br />
wwdb mth143 export mth143-classlist.xml user password permission<br />
<br />
=== Importing a database on the command-line ===<br />
<br />
The <code>wwdb</code> utility is used to export course databases to an XML file.<br />
<br />
The simplest import command is:<br />
<br />
wwdb COURSEID import FILE<br />
<br />
where COURSEID is the name of the course to import to, and FILE is the file to import from. If FILE is =-=, the data will be read from the standard input stream.<br />
<br />
You can additionally specify table names after FILE. If you do, only the data for those tables will be imported. For example, to import all abstract set data to the course calc1:<br />
<br />
wwdb calc1 export calc1-sets.xml set problem<br />
<br />
The <code>-f</code> switch allows <code>wwdb</code> to overwrite records already in the database with the versions in the XML file. If this switch is not given, duplicate records are skipped.<br />
<br />
== The web interface ==<br />
<br />
The web interface provides a user-friendly way to adminsitrate courses. It also allows people who do not have accounts on the WeBWorK server to administrate. Because all actions are performed by the web server, there is no concern about [[#Permissions_issues|permissions problems]] as there is with the command-line utilities.<br />
<br />
=== The 'admin' course ===<br />
<br />
Access to the web-based course administration tools is controlled by a special course named <code>admin</code>. The instructors in this course are permittied to perform administrative functions. If the <code>admin</code> course exists, a '''Course Administration''' link will appear on the WeBWorK home page (usually <code>http://your.server.edu/webwork2</code>).<br />
<br />
Create the admin course using the command-line <code>addcourse</code> tool. The file <code>adminClasslist.lst</code> contains a single user, <code>admin</code>, with password <code>admin</code>.<br />
<br />
If you are using WeBWorK 2.1 or later, we suggest you use the <code>sql_single</code> database layout (if you are using WeBWorK 2.2 or later, only <code>sql_single</code> is supported):<br />
<br />
cd /opt/webwork2/courses<br />
addcourse admin --db-layout=sql_single --users=adminClasslist.lst --professors=admin<br />
<br />
After you create the course, visit the WeBWorK home page on your server, usually located at http://your.server.edu/webwork2. Click on the '''Course Administration''' link. You can also access the <code>admin</code> course directly, at http://your.server.edu/webwork2/admin.<br />
<br />
To log in, enter <code>admin</code> for your username and <code>admin</code> for your password. Once logged into the admin course, the first thing you should do is change the <code>admin</code> password. You can do this by clicking the '''Password/Email''' link on the links menu. After you do this, you may add accounts for any additional people who should have administrative access using the '''Class List Editor''' link.<br />
<br />
=== Creating a course via the web ===<br />
<br />
To create a course, visit the '''Course Administration''' page and select '''Add Course'''. Some notes about the creation process:<br />
<br />
The '''Course Title''' and '''Institution''' fields are used to write an entry to the <code>hosted_courses</code> log, which is intended to help you keep track of created courses.<br />
<br />
'''Add WeBWorK administrators to new course''' copies the users of the <code>admin</code> course to the new course. This can be useful if you need to later go in and modify something for the course's professor.<br />
<br />
Note that the preferred database layout in WeBWorK 2.1 is <code>sql_single</code>. If you are running WeBWorK 2.0, select <code>sql</code> instead -- you will be able to convert the course to use <code>sql_single</code> when you upgrade to 2.1. Only use <code>gdbm</code> if compatibility with WeBWorK 1 is necessary.<br />
<br />
Please note that course names with underscores in them can be an issue, if another course exists with the prefix of this one as its name. See [http://webwork.maa.org/moodle/mod/forum/discuss.php?d=6248 this thread] for more details.<br />
<br />
=== Deleting a course via the web ===<br />
<br />
To delete a course, visit the '''Course Administration''' page and select '''Delete Course'''. In the list of courses, each course's database layout is noted.<br />
<br />
If the course you want to delete uses the <code>sql</code> database layout, you must enter an '''SQL Admin Username''' and '''SQL Admin Password''' for your SQL server. You may also have to specify the '''SQL Server Host''' or the '''SQL Server Port''' if your SQL server is running on a remote machine.<br />
<br />
You will be asked to confirm deletion of the course before it occurs.<br />
<br />
=== Exporting a database via the web ===<br />
<br />
To export a course database, visit the '''Course Administration''' page and select '''Export Database'''. Select a course from the '''Course Name''' list. If you wish to only export a subset of the data in the database, you can deselect one or more of the tables in the '''Tables to Export''' list.<br />
<br />
When you click '''Export Database''', the database file will be sent to your browser.<br />
<br />
=== Importing a database via the web ===<br />
<br />
To import a course database, visit the '''Course Administration''' page and select '''Import Database'''. Select a file to upload in the '''Database XML File''' and select a course from the '''Course Name''' list. If you wish to only import a subset of the data in the XML file, you can deselect one or more of the tables in the '''Tables to Export''' list.<br />
<br />
The '''Conflicts''' option allows you to chose what happens if a duplicate record (a record with the same ID) already exists in the course database. If you select '''Skip duplicate records''', the version in the database will be preserved. If you select '''Replace duplicate records''', the version in the XML file will replace the version in the database.<br />
<br />
When you click '''Import Database''', the database file will be uploaded from your computer and imported.<br />
<br />
== Other administrative functions ==<br />
<br />
=== Converting an existing course from 'sql' to 'sql_single' ===<br />
<br />
The <code>sql_single</code> database layout, new in WeBWorK 2.1, stores course data for multiple courses in a single SQL database. This makes for more efficient database access and avoids exhausing SQL connection handles.<br />
<br />
The command-line utility <code>sql2sql_single</code> can convert existing courses from the <code>sql</code> database layout to the <code>sql_single</code> database layout. As with the other command-line utilities, you must set the <code>WEBWORK_ROOT</code> environment variable and you may add the WeBWorK <code>bin</code> directory to your path.<br />
<br />
To convert a course, the existing course database must be on the same database server as the database used by the <code>sql_single</code> layout. It requires the username and password of an administrative account on the SQL server. <br />
<br />
To convert a course database:<br />
<br />
sql2sql_single course_name webwork root SeCrEt<br />
<br />
Where <code>course_name</code> is the name of an <code>sql</code> course to convert, <code>webwork</code> is the name of the <code>sql_single</code> database, and <code>root</code> and <code>SeCrEt</code> are respecively the username and password of the SQL admin account.<br />
<br />
After running the command, you will need to modify the course's <code>course.conf</code> to set the database layout to <code>sql_single</code>. <code>sql2sql_single</code> will give you the path to the course's course.conf file, but becasue the format of that file is not altogether predictable, you must make the change yourself.<br />
<br />
In <code>course.conf</code>, there should be lines like:<br />
<br />
$dbLayoutName = 'sql';<br />
*dbLayout = $dbLayouts{$dbLayoutName};<br />
<br />
You must change these lines to:<br />
<br />
$dbLayoutName = 'sql_single';<br />
*dbLayout = $dbLayouts{$dbLayoutName};<br />
<br />
The following sed(1) command may be of use:<br />
<br />
sed 's/sql/sql_single/' < course.conf > course.conf.new<br />
mv course.conf course.conf.old<br />
mv course.conf.new course.conf<br />
<br />
=== Adding indexing to an existing course ===<br />
<br />
SQL servers have the ability to maintain indices, to speed access to data. Courses created with the <code>sql_single</code> database layout have indices set up automatically, but if you convert a course from the <code>sql</code> to the <code>sql_single</code> layout, you have to add indexing yourself.<br />
<br />
The <code>wwaddindexing</code> utility adds indices to <code>sql_single</code> courses. As with the other command-line utilities, you must set the <code>WEBWORK_ROOT</code> environment variable and you may add the WeBWorK <code>bin</code> directory to your path.<br />
<br />
This utility is not supported in WeBWorK 2.3 or later.<br />
<br />
To add indices:<br />
<br />
wwaddindexing course_name<br />
<br />
[[Category:Administrators]]</div>Xiong Chiamiovhttps://webwork.maa.org/mediawiki_new/index.php?title=Classlists&diff=2436Classlists2009-08-17T19:31:19Z<p>Xiong Chiamiov: /* Adding new guest (practice) users */ add a note about using different names for the accounts</p>
<hr />
<div>== Sorting and selection ==<br />
<br />
== Editing users ==<br />
<br />
To change user information or [[Permissions|permission level]], do the following:<br />
<br />
# Click '''Classlist Editor''' in the main menu.<br />
# Select '''Edit selected users''' and select the users you want to change passwords for by clicking the checkboxes in the '''Select''' column. You can also chose '''visible users''' or '''all users''' instead of '''selected users''' if you wish.<br />
# Click '''Take Action!'''.<br />
# On the next screen, change user information as you desire. Note that changing a user's '''Student ID''' here does not change the user's password (as it does when adding new users).<br />
# Select '''Save Changes'''.<br />
# Click '''Take Action!'''.<br />
<br />
== Changing passwords ==<br />
<br />
# Click '''Classlist Editor''' in the main menu.<br />
# Select '''Give new passwords to selected users''' and select the users you want to change passwords for by clicking the checkboxes in the '''Select''' column. You can also chose '''visible users''' or '''all users''' instead of '''selected users''' if you wish.<br />
# Click '''Take Action!'''.<br />
# On the next screen, fill in new passwords for each user. If you leave a password blank, the user's password will not be changed.<br />
# Select '''Save changes'''.<br />
# Click '''Take Action!'''.<br />
<br />
You cannot change your own password using this feature. To change your own password, click '''Password/Email''' in the main menu.<br />
<br />
== Adding new users ==<br />
<br />
# Click '''Classlist Editor''' in the main menu.<br />
# Select '''Add ___ Students''' and fill in the number of users you would like to add. (That number just controls the number of input lines you'll get on the next screen. You're not committed to adding that number of users.)<br />
# Click '''Take Action!'''<br />
# On the next screen, fill in values for each item of user data. The '''Login Name''' is required. The user's password will be initially set to the value you give for '''Student ID''' (but you can change it later).<br />
# Select any sets that you would like to assign to the new users. This is a convenience feature {{--}} you can always assign sets to users later.<br />
# Click '''Add Students'''.<br />
<br />
New users are given the default [[Permissions|permission level]], which is "student" by default.<br />
<br />
=== Adding new guest (practice) users ===<br />
<br />
To enable the "login as guest" button, you add "guests" to your course, which in WeBWorK's case are users with login name "practice1", "practice2", etc.<br />
<br />
# Click '''Classlist Editor''' in the main menu.<br />
# Select '''Import users from file <u>demoCourse.lst</u> replacing <u>no</u> existing users and adding <u>any</u> new users'''<br />
# Click '''Take Action!'''<br />
<br />
demoCourse.lst contains 9 practice users, which will allow 9 guests to login at once. If you only have one practice user than only one guest can be logged in at a time. If you delete all the practice users the guest login button goes away. Guests do not have or need specific passwords.<br />
<br />
By default, the practice accounts are named "practice1", "practice2", etc. If you want to call yours "guest001", etc., you can do that by putting<br />
<br />
$practiceUserPrefix = "guest";<br />
<br />
in the couse.conf file for this course.<br />
<br />
You can control the amount of access a guest has using the entries in '''Course Configuration''' (with more choices in the global.conf and course.conf files if you you have direct access to the server).<br />
<br />
== Deleting users ==<br />
<br />
# Click '''Classlist Editor''' in the main menu.<br />
# Select '''Delete no users''' and change '''no users''' to '''selected users'''.<br />
# Select the users you want to change passwords for by clicking the checkboxes in the '''Select''' column.<br />
# Click '''Take Action!'''.<br />
<br />
'''''Please note that there is currently no confirmation for deleting users! Once you click '''Take Action!''', those users, as well as all homework data for them, is gone forever!'''''<br />
<br />
== Importing users from a classlist file ==<br />
<br />
# Click '''File Manager''' in the main menu.<br />
# Below the file list, specify the file you want to upload (this varies by browser -- the button may say something like '''Browse''' or '''Choose File''').<br />
# Click the '''Upload:''' button.<br />
# Click '''Classlist Editor''' in the main menu.<br />
# Select the '''Import users from file''' option and select the file you just uploaded from the first popup menu.<br />
# Decide whether uploaded users should replace existing users using the second popup menu.<br />
# Click '''Take Action!'''.<br />
<br />
''See also: [[Classlist Files]]''<br />
<br />
== Exporting users to a classlist file ==<br />
<br />
== Resource ==<br />
[http://docs.google.com/Presentation?id=dp7p9h5_837c5zcddd7 Roster Management Using the Classlist Editor]<br />
<br />
This links to a publicly viewable Google Docs presentation which illustrates the actions outlined below. The slide show may be embedded in HTML pages and printed. You are welcome to use the slides in any way consistent with the GNU Free Documentation License under which all contributions to this wiki are licensed. Unfortunately, it is not possible to make the presentation publicly editable, but you are welcome to leave any comments or suggestions under the discussion tab for this page. By the way, you may wish to open this in a new tab since otherwise the link will take you away from this site.<br />
<br />
[[Category:Instructors]]<br />
[[Category:Needs Work]]</div>Xiong Chiamiovhttps://webwork.maa.org/mediawiki_new/index.php?title=Classlists&diff=2435Classlists2009-08-17T19:26:12Z<p>Xiong Chiamiov: adding new subsection (under Adding new users) for adding guest users</p>
<hr />
<div>== Sorting and selection ==<br />
<br />
== Editing users ==<br />
<br />
To change user information or [[Permissions|permission level]], do the following:<br />
<br />
# Click '''Classlist Editor''' in the main menu.<br />
# Select '''Edit selected users''' and select the users you want to change passwords for by clicking the checkboxes in the '''Select''' column. You can also chose '''visible users''' or '''all users''' instead of '''selected users''' if you wish.<br />
# Click '''Take Action!'''.<br />
# On the next screen, change user information as you desire. Note that changing a user's '''Student ID''' here does not change the user's password (as it does when adding new users).<br />
# Select '''Save Changes'''.<br />
# Click '''Take Action!'''.<br />
<br />
== Changing passwords ==<br />
<br />
# Click '''Classlist Editor''' in the main menu.<br />
# Select '''Give new passwords to selected users''' and select the users you want to change passwords for by clicking the checkboxes in the '''Select''' column. You can also chose '''visible users''' or '''all users''' instead of '''selected users''' if you wish.<br />
# Click '''Take Action!'''.<br />
# On the next screen, fill in new passwords for each user. If you leave a password blank, the user's password will not be changed.<br />
# Select '''Save changes'''.<br />
# Click '''Take Action!'''.<br />
<br />
You cannot change your own password using this feature. To change your own password, click '''Password/Email''' in the main menu.<br />
<br />
== Adding new users ==<br />
<br />
# Click '''Classlist Editor''' in the main menu.<br />
# Select '''Add ___ Students''' and fill in the number of users you would like to add. (That number just controls the number of input lines you'll get on the next screen. You're not committed to adding that number of users.)<br />
# Click '''Take Action!'''<br />
# On the next screen, fill in values for each item of user data. The '''Login Name''' is required. The user's password will be initially set to the value you give for '''Student ID''' (but you can change it later).<br />
# Select any sets that you would like to assign to the new users. This is a convenience feature {{--}} you can always assign sets to users later.<br />
# Click '''Add Students'''.<br />
<br />
New users are given the default [[Permissions|permission level]], which is "student" by default.<br />
<br />
=== Adding new guest (practice) users ===<br />
<br />
To enable the "login as guest" button, you add "guests" to your course, which in WeBWorK's case are users with login name "practice1", "practice2", etc.<br />
<br />
# Click '''Classlist Editor''' in the main menu.<br />
# Select '''Import users from file <u>demoCourse.lst</u> replacing <u>no</u> existing users and adding <u>any</u> new users'''<br />
# Click '''Take Action!'''<br />
<br />
demoCourse.lst contains 9 practice users, which will allow 9 guests to login at once. If you only have one practice user than only one guest can be logged in at a time. If you delete all the practice users the guest login button goes away. Guests do not have or need specific passwords.<br />
<br />
You can control the amount of access a guest has using the entries in '''Course Configuration''' (with more choices in the global.conf and course.conf files if you you have direct access to the server).<br />
<br />
== Deleting users ==<br />
<br />
# Click '''Classlist Editor''' in the main menu.<br />
# Select '''Delete no users''' and change '''no users''' to '''selected users'''.<br />
# Select the users you want to change passwords for by clicking the checkboxes in the '''Select''' column.<br />
# Click '''Take Action!'''.<br />
<br />
'''''Please note that there is currently no confirmation for deleting users! Once you click '''Take Action!''', those users, as well as all homework data for them, is gone forever!'''''<br />
<br />
== Importing users from a classlist file ==<br />
<br />
# Click '''File Manager''' in the main menu.<br />
# Below the file list, specify the file you want to upload (this varies by browser -- the button may say something like '''Browse''' or '''Choose File''').<br />
# Click the '''Upload:''' button.<br />
# Click '''Classlist Editor''' in the main menu.<br />
# Select the '''Import users from file''' option and select the file you just uploaded from the first popup menu.<br />
# Decide whether uploaded users should replace existing users using the second popup menu.<br />
# Click '''Take Action!'''.<br />
<br />
''See also: [[Classlist Files]]''<br />
<br />
== Exporting users to a classlist file ==<br />
<br />
== Resource ==<br />
[http://docs.google.com/Presentation?id=dp7p9h5_837c5zcddd7 Roster Management Using the Classlist Editor]<br />
<br />
This links to a publicly viewable Google Docs presentation which illustrates the actions outlined below. The slide show may be embedded in HTML pages and printed. You are welcome to use the slides in any way consistent with the GNU Free Documentation License under which all contributions to this wiki are licensed. Unfortunately, it is not possible to make the presentation publicly editable, but you are welcome to leave any comments or suggestions under the discussion tab for this page. By the way, you may wish to open this in a new tab since otherwise the link will take you away from this site.<br />
<br />
[[Category:Instructors]]<br />
[[Category:Needs Work]]</div>Xiong Chiamiovhttps://webwork.maa.org/mediawiki_new/index.php?title=2009_mini-conference_plans&diff=49252009 mini-conference plans2009-07-10T21:36:57Z<p>Xiong Chiamiov: fix link</p>
<hr />
<div>The Portland State University math department has generously offered to host a<br />
mini-conference for WeBWorK developers and "power users". We will hold this on<br />
Wednesday, Aug 5th at the Portland State math department which is a short walk<br />
away from the hotels where the Portland, OR <br />
[http://www.maa.org/MathFest/ Mathfest] will take place from Aug 6th to Aug 8th.<br />
<br />
We are still developing a topics agenda and organizing presentations for this<br />
conference :-). Please add any suggestions for presentations or topics of discussion to <br />
this page.<br />
<br />
* Discuss plans and form a steering committee for joining Google summer of code for the summer of 2010<br />
<br />
* Reports on flash applet, java applet and geogebra integration.<br />
<br />
* "Email instructor button": alternative or additional help methods -- wiki page? moodle forum? connect to MathNerds website? or other? What hooks need to be put into WeBWorK to make these interconnections easy to set up?</div>Xiong Chiamiovhttps://webwork.maa.org/mediawiki_new/index.php?title=Installation_Manual_for_2.4&diff=1363Installation Manual for 2.42009-01-29T21:42:12Z<p>Xiong Chiamiov: /* Creating the admin course */ add note about WEBWORK_ROOT not being found in environment</p>
<hr />
<div>== Installation Methods and Instructions==<br />
* Installing WeBWorK from the WeBWorK Live DVD (see [[Installing_WeBWorK_from_Live_DVD]]) is the fastest method but offers very few choices<br />
* The instructions listed in [[Installation_Manual_for_2.4#Installation instructions for specific operating systems]] offer command-by-command procedures (and fewer choices) than the general instructions. They are targeted at UNIX beginners<br />
* The general instructions on this page offer the most information and choices but are targeted at UNIX experts<br />
* [[Installing_WeBWorK_on_Live_USB]] explains how to download and install a disk image of a fully functioning WeBWorK 2.4 system onto a 2 GB USB flash memory drive. This is suitable for testing WeBWorK<br />
<br />
== Installation instructions for specific operating systems ==<br />
<br />
These manuals offer command-by-command procedures (and fewer choices) than the general instructions. They are targeted at UNIX beginners.<br />
<br />
* [[Installation Manual for 2.4 on Ubuntu 8.04]]<br />
* [[Installation Manual for 2.4 on Fedora 9]]<br />
<br />
[[:Category:Installation_Manuals|More installation manuals...]]<br />
<br />
== Dependencies ==<br />
<br />
=== Apache ===<br />
<br />
WeBWorK supports Apache 1.3 and 2.0. Apache 2.2 is supported experimentally. WeBWorK requires that the <code>mod_alias</code> module be available. Most vendors compile their Apache packages with the necessary features enabled.<br />
<br />
==== Apache 1.3 ====<br />
<br />
* Source: http://httpd.apache.org/<br />
* Debian/Ubuntu: <code>apache</code> <br />
* Red Hat/Fedora: build from source<br />
<br />
==== Apache 2.0 or 2.2 ====<br />
<br />
Apache must be using the <code>prefork</code> MPM. This is because the <code>Safe</code> module, which WeBWorK makes extensive use of, is not threadsafe. This is set at compile time with the <code>--with-mpm=prefork</code> switch to the <code>configure</code> script.<br />
<br />
* Source: http://httpd.apache.org/<br />
* Debian/Ubuntu: <code>apache2</code> with <code>apache2-mpm-prefork</code><br />
* Red Hat/Fedora: build from source; or see below<br />
<br />
''On my Scientific Linux 4 box (i.e., RHEL4) there is no need to recompile apache; mpm-prefork is already set. Of course mod_perl2 must be compiled!'' -- Niels Walet - 13 Mar 2007<br />
<br />
=== Perl ===<br />
<br />
WeBWorK requires Perl 5.6.1 or higher.<br />
<br />
* Source: http://perl.org/<br />
* Debian/Ubuntu: <code>perl</code> (in the default install)<br />
* Red Hat/Fedora: <code>perl</code> (in the default install)<br />
<br />
=== Perl modules ===<br />
<br />
The following Perl modules are required. All are available from [http://cpan.org/ CPAN], and many vendors provide packages of these modules. To see if a module is already installed on your system, use the following command. Replace <code>Module</code> with the name of the module.<br />
<br />
$ perl -MModule -e 'print "installed!\n"'<br />
<br />
<span style="color:red">To determine which of the modules used by WeBWorK are already installed</span> run the script:<br />
webwork2/bin/check_modules.pl [apache1|apache2] <br />
or<br />
perl webwork2/bin/check_modules.pl [apache1|apache2]<br />
which checks for the modules needed for either an apache1 or apache2 installation of WeBWorK respectively. Many of the modules are already installed on most systems. <br />
<br />
A nearly comprehensive<br />
list of the CPAN modules needed are listed in the table below, but <code>check_modules.pl</code> will<br />
be more up to date. For the most part these modules are either already present or can be easily installed using CPAN. Those using compiled binaries for a particular platform may be more quickly and easily installed using packages.<br />
<br />
To install a missing module from CPAN, use the following command as root. Replace <code>Module</code> with the name of the module.<br />
<br />
# perl -MCPAN -e "install Module"<br />
<br />
For more information about using CPAN, consult the [http://cpan.org/misc/cpan-faq.html CPAN FAQ].<br />
<br />
{| border="1"<br />
|-<br />
| '''module'''<br />
| '''Debian/Ubuntu package'''<br />
| '''Gentoo package'''<br />
| '''Fedora Core 7 package'''<br />
|-<br />
| Apache::Constants<br />
|-<br />
| Apache::Cookie/Apache2::Cookie<br />
|-<br />
| Apache::Log<br />
|-<br />
| Apache2::ServerRec<br />
|-<br />
| Apache2::ServerUtil<br />
|-<br />
| Apache::Request<br/><small>(only if using Apache 1.3.x)<br />
| <code>libapache-request-perl</code><br />
| <br />
| <br />
|-<br />
| Apache2::Request<br/><small>(only if using Apache 2.0.x)<br />
| <code>libapache2-request-perl</code><br />
| <code>libapreq</code><br />
| <code>perl-libapreq2</code><br />
|-<br />
| Data::Dumper<br />
|-<br />
| Data::UUID<br />
| <code>libdata-uuid-perl</code> <br><small>(virtual package, provided by <code>libossp-uuid-perl</code>)</small><br />
| <code>Data-UUID</code><br />
| <code>perl-uuid</code><br />
|-<br />
| Date::Format<br />
| <code>libtimedate-perl</code><br />
| <code>TimeDate</code><br />
| <code>perl-TimeDate</code><br />
|-<br />
| Date::Parse<br />
| <code>libtimedate-perl</code><br />
| <code>TimeDate</code><br />
| <code>perl-TimeDate</code><br />
|-<br />
| DateTime<br />
| <code>libdatetime-perl</code><br />
| <code>DateTime</code><br />
| <code>perl-DateTime</code><br />
|-<br />
| DBD::mysql<br />
| <code>libdbd-mysql-perl</code><br />
| <code>DBD-mysql</code><br />
| <code>perl-DBD-MySQL</code><br />
|-<br />
| DBI<br />
|-<br />
| Digest::MD5<br />
|-<br />
| Email::Address<br />
| <code>libemail-address-perl</code><br />
| <code>Email-Address</code><br />
| <code>perl-Email-Address</code><br />
|-<br />
| Errno<br />
|-<br />
| Exception::Class<br />
|-<br />
| File::Copy<br />
|-<br />
| File::Find<br />
|-<br />
| File::Path<br />
|-<br />
| File::Spec<br />
|- <br />
| File::stat<br />
|-<br />
| File::Temp<br />
|-<br />
| GD<br />
| <code>libgd-gd2-perl</code><br />
| <code>GD</code><br />
| <code>perl-GD</code><br />
|-<br />
| Getopt::Long<br />
|-<br />
| Getop::Std<br />
|-<br />
| HTML::Entities<br />
|-<br />
| HTML::Tagset<br />
|-<br />
| IO::File<br />
|-<br />
| Iterator<br />
| not packaged<br />
| not packaged<br />
| not packaged<br />
|-<br />
| Iterator::Util<br />
| not packaged<br />
| not packaged<br />
| not packaged<br />
|-<br />
| Mail::Sender<br />
| <code>libmail-sender-perl</code><br />
| <code>Mail-Sender</code><br />
| <code>perl-Mail-Sender</code><br />
|-<br />
| MIME::Parser<br />
|-<br />
| MIME::Base64<br />
|-<br />
| Net::IP<br />
|-<br />
| Net::LDAPS<br />
|-<br />
| Net::SMTP<br />
|-<br />
| Opcode<br />
|-<br />
| PHP:Serialization<br />
|-<br />
| Pod::Usage<br />
|-<br />
| Safe<br />
|-<br />
| SOAP::Lite<br />
|-<br />
| Socket<br />
|-<br />
| SQL::Abstract<br />
| <code>libsql-abstract-perl</code><br />
| unknown<br />
| <code>perl-SQL-Abstract</code> <br />
|-<br />
| String::ShellQuote<br />
| <code>libstring-shellquote-perl</code><br />
| <code>String-ShellQuote</code><br />
| <code>perl-String-ShellQuote</code><br />
|-<br />
| Text::Wrap<br />
|-<br />
| Time::HiRes<br><small>(included in Perl 5.8 and higher)</small><br />
| included in <code>perl</code> package<br />
| unknown<br />
| included in <code>perl</code> package <br />
|-<br />
| Time::Zone<br />
|-<br />
| URI::Escape<br />
|-<br />
| XML::Parser<br />
| <code>libxml-parser-perl</code><br />
| <code>libxml-perl</code><br />
| <code>perl-XML-Parser</code> <br />
|-<br />
| XML::Parser::EasyTree<br />
| not packaged<br />
| unknown<br />
| not packaged <br />
|-<br />
| XML::Writer<br />
| <code>libxml-writer-perl</code><br />
| <code>XML-Writer</code><br />
| <code>perl-XML-Writer</code><br />
|-<br />
| XMLRPC::Lite <br />
|}<br />
<br />
==== DateTime::TimeZone: use version 0.34 or later ====<br />
<br />
Versions of DateTime::TimeZone (a component of DateTime) below 0.34 suffer from a problem with displaying some time zones. Make sure you have version 0.34 or later.<br />
<br />
==== Problems building Time::HiRes ====<br />
<br />
Some users have reported problems building Time::HiRes through CPAN. If this is your experience, try downloading the Time::HiRes tarball from http://search.cpan.org/~jhi/Time-HiRes/ and building it manually (<code>perl Makefile.PL && make && make test && make install</code>).<br />
<br />
==== Problems building Apache::Request or Apache2::Request ====<br />
<br />
Apache::Request is one component of the libapreq library. If you run into problems building it through CPAN, try downloading the libapreq tarball from http://httpd.apache.org/apreq/.<br />
<br />
Apache 2.0.x users should use libapreq2.<br />
<br />
=== mod_perl ===<br />
<br />
WeBWorK uses mod_perl to interface with the Apache server. If compiling mod_perl from source, use the <code>EVERYTHING=1</code> flag to enable all mod_perl features. Most vendors compile their mod_perl packages with this setting enabled.<br />
<br />
==== Apache 1.3 ====<br />
<br />
* Source: http://perl.apache.org/download/<br />
* Debian/Ubuntu: <code>libapache-mod-perl</code> <br />
* Red Hat/Fedora: build from source; see below.<br />
* Gentoo: <code>mod_perl </code><br />
<br />
==== Apache 2.0 ====<br />
<br />
* Source: http://perl.apache.org/download/ <br />
* Debian/Ubuntu: <code>libapache2-mod-perl</code> <br />
* Red Hat/Fedora: build from source <br />
<br />
==== RHEL4/Fedora build notes ====<br />
<br />
''I had to use the flags below to get the compile to work correctly:''<br />
<br />
perl Makefile.PL EVERYTHING=1 DO_HTTPD=1 USE_APACI=1 APACHE_PREFIX=/usr/local/apache<br />
<br />
-- Main.MarkHamrick<br />
<br />
=== MySQL ===<br />
<br />
MySQL 4.0.x or later is required. If you are going to be using the experimental Moodle Integration, MySQL 4.1.x or later is required.<br />
<br />
* Source: http://dev.mysql.com/downloads/ <br />
* Debian/Ubuntu: 4.0.x: <code>mysql-server</code>; 4.1.x: <code>mysql-server-4.1</code><br />
* RHEL4/Fedora: <code>mysql-sever</code>, <code>mysql-client</code> <br />
* Gentoo: <code>mysql </code><br />
<br />
=== LaTeX ===<br />
<br />
WeBWorK requires LaTeX for generating hardcopy output and displaying mathematics graphically. Any standard LaTeX distribution that provides the commands <code>latex</code> and <code>pdflatex</code> should work. We use TeTeX.<br />
<br />
* Source: http://tug.org/tetex/ <br />
* Debian/Ubuntu: <code>tetex-bin</code>, <code>tetex-extra</code> <br />
* Red Hat/Fedora: <code>tetex</code>, <code>tetex-latex</code> <br />
* Gentoo: <code>tetex</code><br />
<br />
=== Netpbm ===<br />
<br />
WeBWorK requires Netpbm to convert images among the GIF, PNG, and EPS formats.<br />
<br />
* Source: http://netpbm.sf.net/ <br />
* Debian/Ubuntu: <code>netpbm</code> <br />
* Red Hat/Fedora: build from source <br />
* Gentoo: <code>netpbm </code><br />
<br />
=== dvipng ===<br />
<br />
WeBWorK uses dvipng to display mathematics graphically. It is only required if you wish to use the <code>images</code> display mode. dvipng requires the <code>preview.sty</code> file from the [http://preview-latex.sf.net/ preview-latex] package.<br />
<br />
* Source: http://dvipng.sf.net/ <br />
* Debian: <code>dvipng</code>, <code>preview-latex-style</code> <br />
* Red Hat/Fedora: <code>preview-latex-common-0.9.1-1.fedora.noarch.rpm</code> <br />
* Gentoo: <code>dvipng</code> <br />
<br />
WeBWorK is initially configured to work with dvipng 1.0 or greater, but can be reconfigured to work with dvipng 0.8 or 0.9. See <code>webwork2/lib/WeBWorK/Constants.pm</code> for details.<br />
<br />
=== TtH ===<br />
<br />
WeBWorK uses TtH to display mathematics as formatted HTML. It is only required if you wish to use the <code>formatted-text</code> display mode.<br />
<br />
* Source: http://hutchinson.belmont.ma.us/tth/ <br />
* Debian:*|| <code>tth</code><br />
* Red Hat/Fedora: build from source <br />
* Gentoo: <code>tth</code><br />
<br />
== Installing the WeBWorK files ==<br />
<br />
WeBWorK is typically installed using CVS. We provide version tags that correspond to each released version of WeBWorK. This ensures that you can maintain a stable system, and experimental upgrades will not be applied to your installation.<br />
<br />
We also provide tarballs for each release. They contain the necessary CVS data to update from CVS at a later date. Choose a tarball if for some reason you do not want to use CVS. Keep in mind that because of the layout of files within the <code>webwork2</code> directory tree, upgrading an existing installation is harder using a tarball than using CVS.<br />
<br />
=== Creating the base directory directory ===<br />
<br />
Before you begin installing files, create a base directory to hold them. We prefer <code>/opt/webwork</code>:<br />
<br />
# mkdir -p /opt/webwork<br />
<br />
To make things easier during the installation, you can give yourself write permission to this directory. That way, you won't have to become root to install the WeBWorK files:<br />
<br />
# chown yourNameHere /opt/webwork<br />
<br />
=== Installing from CVS ===<br />
<br />
Installing from CVS allows you more flexibility in selecting versions of the WeBWorK code between or ahead of releases. You have several options, depending on which release tag you select when accessing the CVS repository.<br />
<br />
==== CVS tags ====<br />
<br />
'''''Released version:''''' By specifying the '''rel-2-4-1''' tag, you get the same version of the code that you would by downloading the WeBWorK 2.4.1 tarball. This is the most conservative option. Updating will have no effect -- this code will never change.<br />
<br />
'''''Released version with patches:''''' By specifying the '''rel-2-4-patches''' tag, you can stay up to date with the latest bug fixes against the released version of WeBWorK 2.4. Few, if any, new features are introduced on a patch branch. We recommend that you choose this option.<br />
<br />
'''''Latest code:''''' If you do not specify a release tag, you will get the latest code. Since this code is a work in progress, it is sometimes unstable or broken. If you require features that are not in a stable release, and are willing to devote more time to keeping your installation running smoothly, this may be the option for you.<br />
<br />
No matter what tag you chose, you can change later by specifying a new tag when running <code>cvs upgrade</code>.<br />
<br />
==== New installation from CVS ====<br />
<br />
If you do not have an existing WeBWorK installation, use the following commands to check out copies of the <code>webwork2</code> and <code>pg</code> modules. If you are prompted for a password, press enter.<br />
<br />
'''''Released version:'''''<br />
<br />
<code>$ cvs -d :pserver:anoncvs@cvs.webwork.rochester.edu:/webwork/cvs/system checkout -r rel-2-4-1 webwork2</code><br/><br />
<code>$ cvs -d :pserver:anoncvs@cvs.webwork.rochester.edu:/webwork/cvs/system checkout -r rel-2-4-0 pg</code><br />
<br />
'''''Released version with patches:'''''<br />
<br />
<code>$ cvs -d :pserver:anoncvs@cvs.webwork.rochester.edu:/webwork/cvs/system checkout -r rel-2-4-patches webwork2 pg</code><br />
<br />
'''''Latest development code:'''''<br />
<br />
<code>$ cvs -d :pserver:anoncvs@cvs.webwork.rochester.edu:/webwork/cvs/system checkout webwork2 pg</code><br />
<br />
The message <code>warning: cannot open /webwork/cvs/system/CVSROOT/val-tags read/write: Permission denied</code> is harmless and should be ignored.<br />
<br />
After checkout finishes, become root and move the directories to the your installation directory. I prefer <code>/opt/webwork</code>:<br />
<br />
# cp -r webwork2 /opt/webwork/webwork2<br />
# cp -r pg /opt/webwork/pg<br />
<br />
==== Upgrading using CVS ====<br />
<br />
If you already have an existing WeBWorK installation, use the following commands to update your exsting files to version 2.4. You may need to become root to run these commands (depending on your permissions situation).<br />
<br />
Take note of the messages that CVS gives during the update. If you have modified files, you may see the message <code>Merging differences between ''version1'' and ''version2'' into _filename_</code>. This indicates that the file in question is updated in WeBWorK 2.4, and since you also made local modifications to it, CVS is attempting to merge the two changed versions.<br />
<br />
If this process fails, because the same parts of the file were modified in both versions, you will see the message <code>rcsmerge: warning: conflicts during merge</code>. If you end up in this situation, you will need to resolve the conflict by editing the file in question. Consult this [http://ximbiot.com/cvs/manual/cvs-1.11.22/cvs_10.html#SEC85 conflicts example] from the CVS manual.<br />
<br />
The message <code>warning: cannot open /webwork/cvs/system/CVSROOT/val-tags read/write: Permission denied</code> is harmless and should be ignored.<br />
<br />
'''''Released version:'''''<br />
<br />
cd /opt/webwork/webwork2<br />
cvs -q update -dP -r rel-2-4-1<br />
cd /opt/webwork/pg<br />
cvs -q update -dP -r rel-2-4-0<br />
<br />
'''''Released version with patches:'''''<br />
<br />
cd /opt/webwork/webwork2<br />
cvs -q update -dP -r rel-2-4-patches<br />
cd /opt/webwork/pg<br />
cvs -q update -dP -r rel-2-4-patches<br />
<br />
'''''Latest development code:'''''<br />
<br />
cd /opt/webwork/webwork2<br />
cvs -q update -dPA<br />
cd /opt/webwork/pg<br />
cvs -q update -dPA<br />
<br />
=== Installing from a tarball ===<br />
<br />
Tarballs of WeBWorK releases are available from our [http://sf.net/project/showfiles.php?group_id=93112 SourceForge file release] page. You will need to download both a <code>webwork</code> tarball and a <code>pg</code> tarball. Make sure that the versions of the tarballs match. You can choose either a GZip or BZip2 archive.<br />
<br />
After downloading the tarballs, untar them somewhere (like your home directory):<br />
<br />
$ tar -xjf webwork-2.4.1.tar.bz2<br />
$ tar -xjf pg-2.4.0.tar.bz2<br />
<br />
If you have an existing WeBWorK installation, move your existing <code>webwork2</code> and <code>pg</code> directories to <code>webwork2.OLD</code> and <code>pg.OLD</code>, respectively. (You will move your existing courses and configuration over to the new directories later.)<br />
<br />
Then, become root and move the directories to the your installation directory. The installation directory should '''not''' be web-accessible. I prefer <code>/opt/webwork</code>:<br />
<br />
# cp -r webwork-2.4.1 /opt/webwork/webwork2<br />
# cp -r pg-2.4.0 /opt/webwork/pg<br />
<br />
From now on, we will assume that WeBWorK 2 is installed in <code>/opt/webwork/webwork2</code> and PG is installed in <code>/opt/webwork/pg</code>.<br />
<br />
=== Installing fonts for jsMath ===<br />
<br />
jsMath is a display mode that renders math expressions using a JavaScript implementation of the TeX math layout engine. For more information about jsMath, see http://www.math.union.edu/~dpvc/jsmath/.<br />
<br />
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, but this requires a large number of individual character images in a wide range of sizes. These are distributed in <code>webwork2/htdocs/jsMath/jsMath-fonts.tar.gz</code>, and you need to unpack this tarball before jsMath will work properly. Use the command<br />
<br />
$ cd /opt/webwork/webwork2/htdocs/jsMath<br />
$ tar -xzvf jsMath-fonts.tar.gz<br />
<br />
This will unpack the archive. Since there are 20,000 tiny files, it can take a long time, 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, and most students will have results as good as they would with the TeX fonts installed.<br />
<br />
If you do not wish to install the jsMath image fonts (to save space, for example), you should change the value of <code>noImageFonts</code> in the <code>$pg{displayModeOptions}{jsMath}</code> hash in <code>global.conf</code> to 1. This will prevent jsMath from using the image fallback methods.<br />
<br />
See also: [[#jsMath_settings|jsMath settings]]<br />
<br />
=== Creating the courses directory ===<br />
<br />
The courses directory should be located at <code>/opt/webwork/courses</code>. Placing the courses directory outside the <code>webwork2</code> directory makes updates easier.<br />
<br />
You can create your courses directory from the <code>courses.dist</code> directory distributed with WeBWorK. This directory contains the skeleton of a course called <code>modelCourse</code>, which contains the template files for three demo sets. You can opt to copy templates from this set when creating new courses.<br />
<br />
$ cd /opt/webwork/webwork2<br />
$ cp -RPp courses.dist ../courses<br />
<br />
If you prefer not to use <code>modelCourse</code>, you can create an empty courses directory instead:<br />
<br />
$ cd /opt/webwork<br />
$ mkdir courses<br />
<br />
If you are upgrading from WeBWorK 2.2.x, move your existing courses into the new <code>/opt/webwork/courses</code> directory.<br />
<br />
=== Making copies of distribution configuration files ===<br />
<br />
Some files are distributed with the <code>.dist</code> suffix. You must make copies lacking the <code>.dist</code> suffix for WeBWorK to be able to find them. This is done to ease updating with CVS. The <code>.dist</code> files may be updated during a CVS update, but your local versions will be left untouched.<br />
<br />
Before configuring the system, you must make local copies of the <code>global.conf</code> and <code>database.conf</code> configuration files, located in <code>/opt/webwork/webwork2/conf/</code>:<br />
<br />
$ cd /opt/webwork/webwork2/conf<br />
$ cp global.conf.dist global.conf<br />
$ cp database.conf.dist database.conf<br />
<br />
=== Setting permissions ===<br />
<br />
The PG installation directory and files should be owned by root and not writable by other users:<br />
<br />
# cd /opt/webwork/pg<br />
# chown -R root:root .<br />
# chmod -R u+rwX,go+rX .<br />
<br />
Most WeBWorK directories and files should also be owned by root and not writable by other users:<br />
<br />
# cd /opt/webwork/webwork2<br />
# chown -R root:root .<br />
# chmod -R u+rwX,go+rX .<br />
<br />
Certain data directories need to be writable by the web server. These are <code>DATA</code>, <code>courses</code>, <code>htdocs/tmp</code>, <code>logs</code>, and <code>tmp</code>. It is convenient to give WeBWorK administrators access to these directories as well, so they can perform administrative tasks such as removing temporary files, creating and editing courses from the command line, managing logs, and so on.<br />
<br />
The simplest way to set this up assumes that all WeBWorK administrators have root access. In this case, directories that must be writable by the web server should be given the ''group'' of the web server. In the following examples, it is assumed that the web server's group is <code>www-data</code>.<br />
<br />
If you wish to perform administrative tasks without becoming root, you can either add the WeBWorK administrators to the web server's group, or create a new group called <code>wwdata</code>, containing both the WeBWorK administrators and the web server.<br />
<br />
If you chose not to create the <code>wwdata</code> group, the WeBWorK data directories should have the group of the web server:<br />
<br />
# cd /opt/webwork/webwork2<br />
# chgrp -R www-data DATA ../courses htdocs/tmp logs tmp<br />
# chmod -R g+w DATA ../courses htdocs/tmp logs tmp<br />
# find DATA/ ../courses/ htdocs/tmp/ logs/ tmp/ -type d -a ! -name CVS -exec chmod g+s {} \;<br />
<br />
If you chose to create the <code>wwdata</code> group, the WeBWorK directories that must be writable by the web server should have that group:<br />
<br />
# cd /opt/webwork/webwork2<br />
# chgrp -R wwdata DATA ../courses htdocs/tmp logs tmp<br />
# chmod -R g+w DATA ../courses htdocs/tmp logs tmp<br />
# find DATA/ ../courses/ htdocs/tmp/ logs/ tmp/ -type d -a ! -name CVS -exec chmod g+s {} \;<br />
<br />
==== CVS updates and permissions ====<br />
<br />
In the instructions above, you set most WeBWorK and PG files to be owned and only writable by root. If you are planning to do in-place updates of the system with CVS, you may want to set those files to be owned by a regular user instead. That will let you avoid running CVS as root, which could be a security risk. One option is to create a user account that cannot be logged into directly and use it only for WeBWorK files.<br />
<br />
== Configuring your shell ==<br />
<br />
To make working with WeBWorK easier, there are a couple of changes you can make to your shell environment.<br />
<br />
Add the WeBWorK <code>bin</code> directory to your path. This will allow you to run WeBWorK command-line utilities without typing the full path to the utility. If you installed WeBWorK in the default location of <code>/opt/webwork/webwork2</code>, add the directory <code>/opt/webwork/webwork2/bin</code> to your path.<br />
<br />
{| border="1"<br />
|-<br />
| '''if your shell is''' || '''put this line''' || '''in this file''' <br />
|-<br />
| <code>bash</code> || <tt>export PATH=$PATH:/opt/webwork/webwork2/bin</tt> || <code>~/.bashrc</code> <br />
|-<br />
| <code>tcsh</code> || <tt>setenv PATH $PATH:/opt/webwork/webwork2/bin</tt> || <code>~/.cshrc</code> <br />
<br />
|}<br />
<br />
Set the <code>WEBWORK_ROOT</code> environment variable. Some command-line scripts rely on this variable to find other WeBWorK files.<br />
<br />
{| border="1"<br />
|-<br />
| '''if your shell is''' || '''put this line''' || '''in this file''' <br />
|-<br />
| <code>bash</code> || <tt>export WEBWORK_ROOT=/opt/webwork/webwork2</tt> || <code>~/.bashrc</code> <br />
|-<br />
| <code>tcsh</code> || <tt>setenv WEBWORK_ROOT /opt/webwork/webwork2</tt> || <code>~/.cshrc</code> <br />
<br />
|}<br />
<br />
== Configuring WeBWorK ==<br />
<br />
Most WW configuration is done in the file <code>/opt/webwork/webwork2/conf/global.conf</code>. This file provides system-wide configuration settings, and defaults for course settings. Any setting in this file can be overridden in the <code>course.conf</code> file for a particular course.<br />
<br />
There are several options that must be set for WW to work with your system. The rest of the file consists of customization options.<br />
<br />
=== Seed variables ===<br />
<br />
These are the main configuration variables of WeBWorK. The are used by the Apache configuration and by the system itself. Many other settings rely on these variables:<br />
<br />
{| border="1"<br />
|-<br />
| '''variable''' || '''description''' <br />
|-<br />
| <code>$webwork_url</code> || The URL associated with the WeBWorK handler. Usually <code>/webwork2</code>. <br />
|-<br />
| <code>$pg_root</code> || The path to the PG directory. Usually <code>/opt/webwork/pg</code>. <br />
|-<br />
| <code>$webwork_htdocs_url</code> || The URL of static WeBWorK hypertext files. Usually <code>/webwork2_files</code>. <br />
|-<br />
| <code>$webwork_htdocs_dir</code> || The path to the static WeBWorK hypertext files. Usually <code>$webwork_dir/htdocs</code>. <br />
|-<br />
| <code>$webwork_courses_url</code> || The URL of the courses directory. Usually <code>/webwork2_course_files</code>. <br />
|-<br />
| <code>$webwork_courses_dir</code> || The path to the courses directory. Usually <code>$webwork_dir/courses</code>. <br />
<br />
|}<br />
<br />
=== Paths to external programs ===<br />
<br />
To avoid executing malicious code, WW calls external programs using full path names.<br />
<br />
{| border="1"<br />
|-<br />
| '''variable''' || '''description''' <br />
|-<br />
| <code>$externalPrograms{mkdir}</code> || Path to <code>mkdir</code> binary. Usually <code>/bin/mkdir</code>. <br />
|-<br />
| <code>$externalPrograms{mysql}</code> || Path to <code>mysql</code> binary. Usually <code>/usr/bin/mysql</code> or <code>/usr/local/bin/mysql</code>. <br />
|-<br />
| <code>$externalPrograms{tar}</code> || Path to <code>tar</code> binary. Usually <code>/usr/bin/tar</code>. <br />
|-<br />
| <code>$externalPrograms{latex}</code> || Path to <code>latex</code> binary. Usually <code>/usr/bin/latex</code> or <code>/usr/local/bin/latex</code>. <br />
|-<br />
| <code>$externalPrograms{pdflatex}</code> || Path to <code>pdflatex</code> binary. Usually <code>/usr/bin/pdflatex</code> or <code>/usr/local/bin/pdflatex</code>. <br />
|-<br />
| <code>$externalPrograms{dvipng}</code> || Path to <code>dvipng</code> binary. Usually <code>/usr/bin/dvipng</code> or <code>/usr/local/bin/dvipng</code>. <br />
|-<br />
| <code>$externalPrograms{tth}</code> || Path to <code>tth</code> binary. Usually <code>/usr/bin/tth</code> or <code>/usr/local/bin/tth</code>. <br />
|-<br />
| <code>$externalPrograms{giftopnm}</code> || Path to <code>giftopnm</code> binary. Usually <code>/usr/bin/giftopnm</code> or <code>/usr/local/bin/giftopnm</code>. <br />
|-<br />
| <code>$externalPrograms{ppmtopgm}</code> || Path to <code>ppmtopgm</code> binary. Usually <code>/usr/bin/ppmtopgm</code> or <code>/usr/local/bin/ppmtopgm</code>. <br />
|-<br />
| <code>$externalPrograms{pnmtops}</code> || Path to <code>pnmtops</code> binary. Usually <code>/usr/bin/pnmtops</code> or <code>/usr/local/bin/pnmtops</code>. <br />
|-<br />
| <code>$externalPrograms{pnmtopng}</code> || Path to <code>pnmtopng</code> binary. Usually <code>/usr/bin/pnmtopng</code> or <code>/usr/local/bin/pnmtopng</code>. <br />
|-<br />
| <code>$externalPrograms{pngtopnm}</code> || Path to <code>pngtopnm</code> binary. Usually <code>/usr/bin/pngtopnm</code> or <code>/usr/local/bin/pngtopnm</code>. <br />
<br />
|}<br />
<br />
=== Mail settings ===<br />
<br />
WW sends mail in three instances. The PG system sends mail to report answers to questionnaires and free-response problems. The mail merge module is used to send mail to course participants, i.e. to report scores. The feedback module allows participants to send mail to course instructors.<br />
<br />
To send mail, WW needs the address of an SMTP server. When connecting to the SMTP server, it must also send an email address representing the sender of the email.<br />
<br />
{| border="1"<br />
|-<br />
| '''variable''' || '''description''' <br />
|-<br />
| <code>$mail{smtpServer}</code> || The address of an SMTP server. If the local machine is running an SMTP server (as is likely), use <code>localhost</code>. <br />
|-<br />
| <code>$mail{smtpSender}</code> || The address to send when connecting to the SMTP server. This has nothing to do with the <code>From</code> address on the mail message. <br />
<br />
|}<br />
<br />
=== Database settings ===<br />
<br />
The following settings are used in connecting to the MySQL database.<br />
<br />
{| border="1"<br />
|-<br />
| '''variable''' || '''description''' <br />
|-<br />
| <code>$database_dsn</code> || The location of the WeBWorK database. Usually <code>dbi.mysql.webwork</code>. See the Perl DBI documentation for more information about DSNs. <br />
|-<br />
| <code>$database_username</code> || The username to use when connecting to the database. Usually <code>webworkWrite</code>. <br />
|-<br />
| <code>$database_password</code> || The password to use when connecting to the database. Use a secure, random password of sufficient length. <br />
<br />
|}<br />
<br />
The <code>$dbLayoutName</code> variable controls the default database layout that will be used for new courses. If you plan to use MoodleIntegration on all new courses, set this to "sql_moodle". Otherwise, leave it set to the default, "sql_single".<br />
<br />
You can override the default when creating a new course.<br />
<br />
=== Timezone setting ===<br />
<br />
You can set the local timezone to use when displaying times using the <code>$siteDefaults{timezone}</code> setting. To get a list of timezone names, run:<br />
<br />
$ perl -MDateTime::TimeZone -e 'print join "\n", DateTime::TimeZone::all_names'<br />
<br />
To get a list of valid timezone "links" (deprecated names), run:<br />
<br />
$ perl -MDateTime::TimeZone -e 'print join "\n", DateTime::TimeZone::links'<br />
<br />
Links can be shorter and more familiar, but they may be ambiguous.<br />
<br />
=== Display modes ===<br />
<br />
WeBWorK has several techniques for displaying homework problems. Which of these modes is available is controlled by the <code>$pg{displayModes}</code> list. To disable a display mode, comment out its line from the list by inserting a <code>#</code> character at the beginning of the line.<br />
<br />
The supported display modes are as follows:<br />
<br />
{| border="1"<br />
|-<br />
| '''display mode''' || '''status''' || '''description''' <br />
|-<br />
| <code>plainText</code> || STABLE || This mode shows the raw TeX source of mathematics. It is useful for debugging. <br />
|-<br />
| <code>formattedText</code> || DEPRECATED || This mode uses the <code>tth</code> program to represent mathematics as HTML table structures. Output quality depends on the browser. There are typically font problems on the Mac platform. <br />
|-<br />
| <code>images</code> || STABLE || This mode uses the <code>dvipng</code> program to represent mathematics as PNG images. This gives excellent output on all browsers, but uses more bandwidth, as the images must be sent to the client. <br />
|-<br />
| <code>jsMath</code> || STABLE || This mode uses jsMath to display mathematics. The raw TeX is sent to the client, where a JavaScript program displays it. This requires the client to have a decent JavaScript implementation, and can be slow on older machines. <br />
|-<br />
| <code>asciimath</code> || DEPRECATED || This mode converts mathematics to ASCIIMath on the server and uses a <nobpo>JavaScript to convert them to MathML on the client. Requires a Mozilla-based browser or MSIE with the MathPlater plugin. <br />
|-<br />
| <code>LaTeXMathML</code> || EXPERIMENTAL || This mode is a modification of the <code>asciimath</code> mode that skips the intermediate ASCIIMath form. Requires a Mozilla-based browser or MSIE with the MathPlater plugin. <br />
<br />
|}<br />
<br />
=== jsMath settings ===<br />
<br />
When a student doesn't have the TeX fonts installed, jsMath can display a warning message pointing to the jsMath font download site. Since the image-mode fallback method is of high enough quality, most students will not feel the need to download and install the fonts, so this warning message is disabled by default. (It tended to worry the students, and there is a link to the download page on the control panel that is new in version 2.0 of jsMath).<br />
<br />
jsMath settings are stored in the <code>$pg{displayModeOptions}{jsMath}</code> hash:<br />
<br />
{| border="1"<br />
|-<br />
| '''variable''' || '''description''' <br />
|-<br />
| <code>reportMissingFonts</code> || Set to 1 if you want to have a message displayed for students who don't have the TeX fonts installed. The warning will only be shown on the first page they view that used jsMath (and there is a "hide" button that they can use to hide it even on that page). They can use the control panel to disable the warning messages permanently for their computer, if they want, so even if you turn on the warning message, it is not too intrusive. <br />
|-<br />
| <code>missingFontMessage</code> || An HTML string that will be used for the missing font message (when <code>reportMissingFonts</code> is non-zero). This string will replace the default warning message, and can be used to point to your own page of instructions for getting the fonts, for example, or for using the control panel to disable the warning. <br />
|-<br />
| <code>noImageFonts</code> || Set to 1 to prevent jsMath from using the image fallback method. This can be useful if you elected not to unpack the <code>jsMath-fonts.tar.gz</code> archive. <br />
|-<br />
| <code>processDoubleClicks</code> || By default, double-clicking on the math expression will display the TeX source that generated it. If you wish to disable this behavior, set this to 0. (Note that the raw TeX is still available in the page's HTML source.) <br />
<br />
|}<br />
<br />
== Configuring the database ==<br />
<br />
WeBWorK uses a single MySQL database to store course data. By default, this database is named <code>webwork</code> and is accessed by a MySQL user named <code>webworkWrite</code>.<br />
<br />
=== Creating a new database ===<br />
<br />
If this is a new installation, you must create the <code>webwork</code> database:<br />
<br />
$ mysql -u root -p mysql<br />
Password: '''***'''<br />
> CREATE DATABASE webwork;<br />
> GRANT SELECT, INSERT, UPDATE, DELETE, CREATE, ALTER, DROP, LOCK TABLES<br />
ON webwork.* TO webworkWrite@localhost IDENTIFIED BY 'password';<br />
> exit<br />
Bye<br />
$ <br />
<br />
(Replace <code>password</code> with the password you set for <code>$database_password</code> in <code>global.conf</code>.)<br />
<br />
=== Using an existing database ===<br />
<br />
If you already have a <code>webwork</code> database from WeBWorK 2.1.x or 2.2.x, you must run the utility <code>wwdb_check</code> to make sure that it is up-to-date for use with 2.4.x. You should '''not''' use this utility if you are upgrading from 2.3.x or an earlier version of 2.4.x. (For example, from 2.4.1 to 2.4.2.)<br />
<br />
To run the utility:<br />
<br />
$ /opt/webwork/webwork2/bin/wwdb_check<br />
<br />
The script will look at the structure of your <code>webwork</code> database, and alert you to missing tables, missing fields, and incorrect field types. You will have the option to fix these problems.<br />
<br />
WeBWorK 2.4 requires permision to <code>LOCK TABLES</code> in the <code>webwork</code> database. Use the <code>mysql</code> console to add it:<br />
<br />
$ mysql -u root mysql<br />
Password: '''***'''<br />
> GRANT LOCK TABLES ON webwork.* TO webworkWrite@localhost;<br />
> exit;<br />
$<br />
<br />
=== Automated database initialization and upgrade ===<br />
<br />
WeBWorK 2.3.0 introduces an automatic database upgrade system. Rather than manually issuing SQL commands to make changes to the database, or using ad-hoc scripts like <code>wwdb_addgw</code>, there is a single script called <code>wwdb_upgrade</code> that applies any necessary updates. It should be run when creating a new database, and any time you upgrade WeBWorK.<br />
<br />
$ /opt/webwork/webwork2/bin/wwdb_upgrade<br />
<br />
Add the <code>-v</code> switch to get more information about what the script is doing.<br />
<br />
=== Image depths database ===<br />
<br />
The "images" display mode has the capability to store depth information in a <code>depths</code> table when equation images are generated. The information allows better alignment of images with surrounding text. In previous versions of WeBWorK, the <code>depths</code> table was stored in a separate database, named <code>DvipngDepths</code>. Starting with WeBWorK 2.3.0, it is stored in the <code>webwork</code> database itself.<br />
<br />
If you are upgrading an existing installation, and you had set <code>$pg{displayModeOptions}{images}{dvipng_align}</code> to <code>mysql</code> in the old version, you have depths information stranded in your old <code>DvipngDepths</code> database, and existing images will lose access to this information.<br />
<br />
The easiest way to solve this is to delete the existing images. This is probably a good idea anyway when upgrading since existing images won't take advantage of rendering improvements, dvipng improvements, etc. To delete the images:<br />
<br />
$ /opt/webwork/webwork2/bin/remove_stale_images --days=0 --delete<br />
<br />
== Configuring Apache ==<br />
<br />
=== Testing mod_perl ===<br />
<br />
To verify that mod_perl is installed, you can use mod_info to list the installed modules. If mod_info itself is disabled or not installed, you can either install/enable it, or skip this test and check using Apache::Status instead. The process for installing and enabling modules varies by distribution. To configure mod_perl, uncomment the location block <code>&lt;Location /server-info&gt;</code> in your Apache config file (usually <code>httpd.conf</code> or <code>apache.conf</code>). It should look something like this:<br />
<br />
<Location /server-info><br />
SetHandler server-info<br />
Order deny,allow<br />
Deny from all<br />
Allow from localhost<br />
Allow from .yourschool.edu<br />
</Location><br />
<br />
You may have to add the <code>Order</code>, <code>Deny</code>, and <code>Allow</code> lines yourself, or there may already be lines there you can customize. Restart Apache (<code>apachectl graceful</code>) and visit <code>http://yourserver.yourschool.edu/server-info</code>. You should see an entry in the list of active modules for mod_perl.<br />
<br />
To further test mod_perl, you can install the Perl module Apache::Status. After installing, add the following section to your Apache config file:<br />
<br />
<Location /perl-status><br />
SetHandler perl-script<br />
PerlHandler Apache::Status<br />
Order deny,allow<br />
Deny from all<br />
Allow from localhost<br />
Allow from .yourschool.edu<br />
</Location><br />
<br />
Restart Apache (<code>apachectl graceful</code>) and visit <code>http://yourserver.yourschool.edu/perl-status</code>. You should see a page listing various information about mod_perl.<br />
<br />
=== Enabling WeBWorK ===<br />
<br />
Once mod_perl is working, Apache must be configured to handle requests for WeBWorK. Apache provides access to WeBWorK through three URL locations:<br />
<br />
* The location that is handled by the <code>Apache::WeBWorK</code> module, usually <code>/webwork2</code>.<br />
* The location of system-wide resources, usually <code>/webwork2_files</code>.<br />
* The location of course-specific resources, usually <code>/webwork2_course_files</code>.<br />
<br />
WeBWorK ships with an Apache config file that you can include in your main Apache config file. The file is named <code>webwork.apache-config.dist</code> and located in the <code>conf</code> directory. First, copy the file to <code>webwork.apache-config</code>:<br />
<br />
$ cd /opt/webwork/webwork2/conf<br />
$ cp webwork.apache-config.dist webwork.apache-config<br />
<br />
Then, edit the copy to set the <code>$webwork_dir</code> variable to the path of the directory containing the WeBWorK installation. This is usually <code>/opt/webwork/webwork2</code>. This value is used to read the WeBWorK configuration file and get the rest of the configuration data.<br />
<br />
Further down in the file, you may want to customize the directives used to define the association between Apache and WeBWorK. Specifically, you may need to add the following to the <code>&lt;Location&gt;</code> and <code>&lt;Directory&gt;</code> stanzas, to permit access:<br />
<br />
Order allow,deny<br />
Allow from all<br />
<br />
After editing <code>webwork.apache-config</code>, append the following line to your Apache configuration file:<br />
<br />
Include /opt/webwork/webwork2/conf/webwork.apache-config<br />
<br />
If you are upgrading from a previous version of WeBWorK which did not use the <code>webwork.apache-config</code> file, you will need to remove the WeBWorK-related directives from your Apache configuration.<br />
<br />
Then restart Apache and test your configuration:<br />
<br />
* Test the <code>/webwork2</code> location by visiting <code>http://yourserver.yourschool.edu/webwork2</code>. You should see the WeBWorK home page, with no courses listed.<br />
* Test the <code>/webwork2_files</code> location by visiting <code>http://yourserver.yourschool.edu/webwork2_files</code>. You should see the "WeBWorK Placeholder Page".<br />
* You cannot test the <code>/webwork2_course_files</code> location until you have created a course.<br />
<br />
=== Experimental support for Apache 2.0.x ===<br />
<br />
If you are using Apache 2.0.x, follow the directions above, with these changes:<br />
<br />
Enable the libapreq module by adding the following line to your Apache2 configuration file. Place this line with the other <code>LoadModule</code> lines.<br />
<br />
LoadModule apreq_module modules/mod_apreq.so<br />
<br />
Use the module Apache2::Status in place of Apache::Status.<br />
<br />
Use the file <code>webwork.apache2-config</code> in place of <code>webwork.apache-config</code>.<br />
<br />
== Creating the admin course ==<br />
<br />
WeBWorK includes web-based course management tools. Access to these tools is controlled by a special course named <code>admin</code>. The instructors in this course are permittied to perform administrative functions. If the admin course exists, a '''Course Administration''' link will appear on the WeBWorK home page.<br />
<br />
If you created a <code>wwadmin</code> group, create the admin course as follows:<br />
<br />
$ cd /opt/webwork/courses<br />
$ newgrp wwadmin<br />
$ umask 2<br />
$ addcourse<br />
$ addcourse admin --db-layout=sql_single --users=adminClasslist.lst --professors=admin<br />
$ exit<br />
<br />
If you did not create a <code>wwadmin</code> group, create the admin course as follows:<br />
<br />
$ sudo -u www-data addcourse admin --db-layout=sql_single --users=adminClasslist.lst --professors=admin<br />
<br />
Replace <code>www-data</code> with the user your webserver runs as.<br />
<br />
See CourseAdministrationManual#Permissions_issues for more about getting the permission right when using the command-line tools.<br />
<br />
If you get an error about WEBWORK_ROOT not being found in the environment (and it is set in your ~/.bashrc), try this instead:<br />
<br />
$ sudo -u www-data env WEBWORK_ROOT=/opt/webwork/webwork2 addcourse admin --db-layout=sql_single --users=adminClasslist.lst --professors=admin<br />
<br />
After you create the course, visit the WeBWorK home page on your server, usually located at <code>http://yourserver.yourschool.edu/webwork2</code>. Click on the '''Course Administration''' link. You can also access the admin course directly, at <code>http://yourserver.yourschool.edu/webwork2/admin</code>.<br />
<br />
To log in, enter <code>admin</code> for your username and <code>admin</code> for your password. Once logged into the admin course, the first thing you should do is change the password for the admin account. You can do this by clicking the '''Password/Email''' link on the links menu. After you do this, you may add accounts for any additional people who should have administrative access using the '''Class List Editor''' link.<br />
<br />
== Where to go from here ==<br />
<br />
Read [[Course Administration]] for more information about managing courses.<br />
<br />
Read [[Problem Libraries]] for information on installing libraries of pre-written WeBWorK problems.<br />
<br />
Read [[Moodle Integration]] for information on including WeBWorK problem sets in Moodle courses. (Experimental)<br />
<br />
Read [[LDAP Authentication]] for information about LDAP authentication. (Experimental)<br />
<br />
Consult [[:Category:Administrators]] for other WeBWorK documentation for system administrators.<br />
<br />
[[Category:Installation Manuals]]</div>Xiong Chiamiovhttps://webwork.maa.org/mediawiki_new/index.php?title=User_talk:Sam&diff=4592User talk:Sam2009-01-22T23:02:04Z<p>Xiong Chiamiov: New page: User talk:David2100 is back, btw. [http://www.mediawiki.org/wiki/Extension:Title_Blacklist Title Blacklist] could be useful. ~~~~</p>
<hr />
<div>[[User talk:David2100]] is back, btw. [http://www.mediawiki.org/wiki/Extension:Title_Blacklist Title Blacklist] could be useful. [[User:Xiong Chiamiov|Xiong Chiamiov]] 18:02, 22 January 2009 (EST)</div>Xiong Chiamiovhttps://webwork.maa.org/mediawiki_new/index.php?title=SimplifiedEntry&diff=3855SimplifiedEntry2008-08-24T15:14:38Z<p>Xiong Chiamiov: get rid of all that html and use wikimarkup instead</p>
<hr />
<div>In order to facilitate the creation of problems in WebWork, it seems necessary to streamline and simplify the problem generation process while at the same time providing a method for basic problem generation that newcomers can use that avoids much of the difficulty associated with mastery of the PG language.<br />
<br />
We propose two new approaches here to the problem authoring facility built in to WebWork that focus on either:<br />
# building problems in a more controlled fashion that hides the details of the PG language or that<br />
# allows authoring of PG problems via a TeX-like interface<br />
<br />
This would potentially make problem input for beginners more tractable in the PG language and encourage more widespread problem development.<br />
<br />
==A Segmented Edit Page==<br />
One approach is to create a redesigned version of the existing edit page could be created that provides a more graphical user interface the PG problem edit mechanism. An example of this is provided in the link above. In this page, the essential parts of a PG problem are split into areas that are more controlled and that hide portions of the PG backend. This also presents a cleaner version of a problem and would help to prevent confusion surrounding how problems work.<br />
<br />
==A Hybrid PG/Tex Authoring Mode==<br />
In general, it also seems appealing to be able to author problems in a PG/LaTeX hybrid mode where the formulas and problem formatting are determined by LaTeX commands and the WebWork problem aspects ( answer rules, random parameters, etc.) are handled by keyword tags. This PGTex could then be processed by a perl script into true PG for inclusion into problem sets. This approach offers several advantages.<br />
<br />
# First of all, the existing problem editing facility can be modified to support this PGTex entry mode in a Basic Editor version that would be accessible from a different URL within WebWork. It would limit the available problem types, but would allow for quick, easy problem generation for people familiar with TeX.<br />
# Secondly, external applications could be adapted to use this problem generation mode. For example, LyX, a LaTeX typesetting application, could be adapted to use this problem processing externally and the resulting PGTex could be uploaded and processed by WebWork in the same way as with the built in Basic Editor.<br />
# It also would permit the basic aspects of a PG problem, e.g. macro loading, etc., to be suppressed for users who have no interest in understand the more complicated aspects of PG problem authoring<br />
# It would abstract out the encoding of things like functions and answer comparisons so that changes to the macro library could be made transparent in some sense (maybe)<br />
<br />
The Basic Editor could also be adapted to utilize a GUI like TeX editor such as the HTML editor in Moodle (that is used to create Wiki entries) further simplifying the creation of problems.<br />
<br />
==TODO==<br />
* create the Tex2PG processor within WebWork<br />
* create a modified version of PGProblemEditor.pm that supports PGTex editing<br />
* develop a secure way for external applications to upload files for processing (perhaps using the xmlrpc connection for preview as well)<br />
* [[EditorDesigns]]<br />
[[Category:AIMWeBWorK Working Groups]]</div>Xiong Chiamiovhttps://webwork.maa.org/mediawiki_new/index.php?title=SimplifiedEntry&diff=3854SimplifiedEntry2008-08-24T15:07:24Z<p>Xiong Chiamiov: no embedding html in wiki-pages!</p>
<hr />
<div>In order to facilitate the creation of problems in WebWork, it seems necessary to streamline and simplify the problem generation process while at the same time providing a method for basic problem generation that newcomers can use that avoids much of the difficulty associated with mastery of the PG language.<br /><br />We propose two new approaches here to the problem authoring facility built in to WebWork that focus on either <br /><br />
<ul><br />
<li>building problems in a more controlled fashion that hides the details of the PG language or that <br /></li><br />
<li>allows authoring of PG problems via a TeX-like interface<br /></li><br />
</ul>This would potentially make problem input for beginners more tractable in the PG language and encourage more widespread problem development. <br /><br /><br /><span style="text-decoration: underline;"><span style="font-weight: bold;">A Segmented Edit Page<br /></span></span><br />One approach is to create a redesigned version of the existing edit page could be created that provides a more graphical user interface the PG problem edit mechanism. An example of this is provided in the link above. In this page, the essential parts of a PG problem are split into areas that are more controlled and that hide portions of the PG backend. This also presents a cleaner version of a problem and would help to prevent confusion surrounding how problems work.<br /><br /><br /><span style="text-decoration: underline;"><span style="font-weight: bold;">A Hybrid PG/Tex Authoring Mode</span></span><br />In general, it also seems appealing to be able to author problems in a PG/LaTeX hybrid mode where the formulas and problem formatting are determined by LaTeX commands and the WebWork problem aspects ( answer rules, random parameters, etc.) are handled by keyword tags. This PGTex could then be processed by a perl script into true PG for inclusion into problem sets. This approach offers several advantages.<br />
<ul><br />
</ul><br />
<ul><br />
<li>First of all, the existing problem editing facility can be modified to support this PGTex entry mode in a Basic Editor version that would be accessible from a different URL within WebWork. It would limit the available problem types, but would allow for quick, easy problem generation for people familiar with TeX.</li><br />
<ul>&nbsp;<br />
</ul><br />
<li>Secondly, external applications could be adapted to use this problem generation mode. For example, LyX, a LaTeX typesetting application, could be adapted to use this problem processing externally and the resulting PGTex could be uploaded and processed by WebWork in the same way as with the built in Basic Editor. <br /></li><br />
<li>It also would permit the basic aspects of a PG problem, e.g. macro loading, etc., to be suppressed for users who have no interest in understand the more complicated aspects of PG problem authoring</li><br />
<li>It would abstract out the encoding of things like functions and answer comparisons so that changes to the macro library could be made transparent in some sense (maybe)<br /></li><br />
<ul>&nbsp;<br />
</ul><br />
</ul>The Basic Editor could also be adapted to utilize a GUI like TeX editor such as the HTML editor in Moodle (that is used to create Wiki entries) further simplifying the creation of problems.<br /><br /><br />TODO: <br /><br />
<ul><br />
<li>create the Tex2PG processor within WebWork</li><br />
<li>create a modified version of PGProblemEditor.pm that supports PGTex editing</li><br />
<li>develop a secure way for external applications to upload files for processing (perhaps using the xmlrpc connection for preview as well)<br /></li><br />
</ul><br /><br /> <br />
* [[EditorDesigns]]<br />
[[Category:AIMWeBWorK Working Groups]]</div>Xiong Chiamiovhttps://webwork.maa.org/mediawiki_new/index.php?title=SimplifiedEntry&diff=3853SimplifiedEntry2008-08-24T15:05:46Z<p>Xiong Chiamiov: remove link I couldn't manage to find; if you know the location of the intended page, please add it back in in proper wiki-syntax</p>
<hr />
<div>In order to facilitate the creation of problems in WebWork, it seems necessary to streamline and simplify the problem generation process while at the same time providing a method for basic problem generation that newcomers can use that avoids much of the difficulty associated with mastery of the PG language.<br /><br />We propose two new approaches here to the problem authoring facility built in to WebWork that focus on either <br /><br />
<ul><br />
<li>building problems in a more controlled fashion that hides the details of the PG language or that <br /></li><br />
<li>allows authoring of PG problems via a TeX-like interface<br /></li><br />
</ul>This would potentially make problem input for beginners more tractable in the PG language and encourage more widespread problem development. <br /><br /><br /><span style="text-decoration: underline;"><span style="font-weight: bold;">A Segmented Edit Page<br /></span></span><br />One approach is to create a redesigned version of the existing edit page could be created that provides a more graphical user interface the PG problem edit mechanism. An example of this is provided in the link above. In this page, the essential parts of a PG problem are split into areas that are more controlled and that hide portions of the PG backend. This also presents a cleaner version of a problem and would help to prevent confusion surrounding how problems work.<br /><br /><br /><span style="text-decoration: underline;"><span style="font-weight: bold;">A Hybrid PG/Tex Authoring Mode</span></span><br />In general, it also seems appealing to be able to author problems in a PG/LaTeX hybrid mode where the formulas and problem formatting are determined by LaTeX commands and the WebWork problem aspects ( answer rules, random parameters, etc.) are handled by keyword tags. This PGTex could then be processed by a perl script into true PG for inclusion into problem sets. This approach offers several advantages.<br />
<ul><br />
</ul><br />
<ul><br />
<li>First of all, the existing problem editing facility can be modified to support this PGTex entry mode in a Basic Editor version that would be accessible from a different URL within WebWork. It would limit the available problem types, but would allow for quick, easy problem generation for people familiar with TeX.</li><br />
<ul>&nbsp;<br />
</ul><br />
<li>Secondly, external applications could be adapted to use this problem generation mode. For example, LyX, a LaTeX typesetting application, could be adapted to use this problem processing externally and the resulting PGTex could be uploaded and processed by WebWork in the same way as with the built in Basic Editor. <br /></li><br />
<li>It also would permit the basic aspects of a PG problem, e.g. macro loading, etc., to be suppressed for users who have no interest in understand the more complicated aspects of PG problem authoring</li><br />
<li>It would abstract out the encoding of things like functions and answer comparisons so that changes to the macro library could be made transparent in some sense (maybe)<br /></li><br />
<ul>&nbsp;<br />
</ul><br />
</ul>The Basic Editor could also be adapted to utilize a GUI like TeX editor such as the HTML editor in Moodle (that is used to create Wiki entries <img title="big grin" alt="big grin" src="http://aimwebwork-int.openwebwork.org/moodle/pix/s/biggrin.gif" /> ) further simplifying the creation of problems.<br /><br /><br />TODO: <br /><br />
<ul><br />
<li>create the Tex2PG processor within WebWork</li><br />
<li>create a modified version of PGProblemEditor.pm that supports PGTex editing</li><br />
<li>develop a secure way for external applications to upload files for processing (perhaps using the xmlrpc connection for preview as well)<br /></li><br />
</ul><br /><br /> <br />
* [[EditorDesigns]]<br />
[[Category:AIMWeBWorK Working Groups]]</div>Xiong Chiamiovhttps://webwork.maa.org/mediawiki_new/index.php?title=SamsExampleProblem&diff=3938SamsExampleProblem2008-08-20T17:50:34Z<p>Xiong Chiamiov: update dead link</p>
<hr />
<div> <br />
# PG problems are essentially Perl source files, with one exception: Perl<br />
# backslashes (\) are replaced by double-tildes (~~) since TeX uses<br />
# backslashes. For more about the format of PG files, consult the Translator.pm<br />
# documentation at:<br />
# <http://webwork.maa.org/doc/cvs/pg_HEAD/lib/WeBWorK/PG/Translator.html><br />
<br />
# The first section in this file is a list of tags for the database problem<br />
# library project. For more about the tagging format, look at:<br />
# <http://hobbes.la.asu.edu/webwork-stuff/Tagging.html><br />
<br />
##DESCRIPTION<br />
## Plots a piecewise function made up of a horizontal line, a diagonal line, and<br />
## a parabola and asks the student to determine the derivative at various<br />
## interesting points.<br />
##ENDDESCRIPTION<br />
## DBsubject('Calculus')<br />
## DBchapter('Limits and Derivatives')<br />
## DBsection('Definition of the Derivative')<br />
## KEYWORDS('calculus', 'derivatives', 'slope')<br />
## TitleText1('Calculus')<br />
## EditionText1('1')<br />
## AuthorText1('Rogawski')<br />
## Section1('3.1')<br />
## Problem1('11')<br />
## Author('Sam Hathaway')<br />
## Institution('W.H.Freeman')<br />
<br />
# The DOCUMENT() call sets up initial values for PG internals. It should always<br />
# be the first executable line in the problem.<br />
DOCUMENT();<br />
<br />
# loadMacros() calls load macro files (which are Perl source files) into the<br />
# problem environment. These first three files are required by all problems.<br />
# Documentation:<br />
# <http://devel.webwork.rochester.edu/doc/cvs/pg_HEAD/macros/PG.pl.html><br />
# <http://devel.webwork.rochester.edu/doc/cvs/pg_HEAD/macros/PGbasicmacros.pl.html><br />
# <http://devel.webwork.rochester.edu/doc/cvs/pg_HEAD/macros/PGanswermacros.pl.html><br />
loadMacros("PG.pl","PGbasicmacros.pl","PGanswermacros.pl");<br />
<br />
# Parser.pl is the main macro file for MathObjects. This file defines macros<br />
# such as Real() and Formula(). You'll load it in pretty much all problems.<br />
# Parser docs are available at:<br />
# <http://devel.webwork.rochester.edu/twiki/bin/view/Webwork/MathObjects><br />
loadMacros("Parser.pl");<br />
<br />
# This is our macro file that provides the textbook_ref_exact() and<br />
# textbook_ref_corr() macros. You'll load it in all problems.<br />
loadMacros("freemanMacros.pl");<br />
<br />
# This macro file contains the ceil(), floor(), max(), and (min) macros, which<br />
# we use in this problem. If you're not using macros from this package, you do<br />
# not need to load it.<br />
loadMacros("PGauxiliaryFunctions.pl");<br />
<br />
# This macro file contains the init_graph() and plot_functions() macros. We need<br />
# these to create the graph for this problem. Don't load this unless you need<br />
# it. Documentation at:<br />
# <http://devel.webwork.rochester.edu/doc/cvs/pg_HEAD/macros/PGgraphmacros.pl.html><br />
loadMacros("PGgraphmacros.pl");<br />
<br />
# These are the values in the book version of the problem. Note that they are<br />
# commented out.<br />
#$base = 1;<br />
#$rise = 2;<br />
#$vertex_y = -2.25;<br />
<br />
# Here are the randomized values. Each student will get a different (but<br />
# persistent) value from each of these calls.<br />
$base = random(1,3,1);<br />
$rise = random(1,2,1);<br />
$vertex_y = random(1,4,0.25)*list_random(-1,1);<br />
<br />
# Create a MathObject formula for the initial height of the first horizontal<br />
# line.<br />
$horiz_line = Formula($base);<br />
<br />
# Represent the slope of the diagonal line. Set the reduceConstants flag of the<br />
# MathObjects context to 0, so that "$rise/2" is not reduced.<br />
Context()->flags->set(reduceConstants=>0);<br />
$slope = Formula("$rise/2");<br />
<br />
# This is the formula for the diagonal line.<br />
$diag_line = Formula("$slope*(x-3)+$base");<br />
<br />
# This is the formula for the parabola.<br />
$par = Formula("-($vertex_y/4)(x-5)(x-9)+$base+$rise");<br />
<br />
# Get the y-value of the vertex of the porabola. We know that it occurs at x=7,<br />
# so we evaluate the $par formula with at x=7.<br />
$real_vertex = $par->eval(x=>7);<br />
<br />
# Now we set some temporary variables that we'll pass into init_graph below:<br />
<br />
# Minimum and maximum x and y values to graph.<br />
$xmin = -1;<br />
$ymin = min(-1, ceil($real_vertex)-1);<br />
$xmax = 9;<br />
$ymax = max(5, $base+$rise+1, floor($real_vertex)+1);<br />
<br />
# We want grid lines on each integer value, but we have to specify the total<br />
# number of grid lines on each axis, so we just use the x and y range.<br />
$xrange = $xmax-$xmin;<br />
$yrange = $ymax-$ymin;<br />
<br />
# Size of the graph in pixels.<br />
$xsize = $xrange*25;<br />
$ysize = $yrange*25;<br />
<br />
# init_graph returns a graph object that we can then add functions to.<br />
$graph = init_graph(<br />
$xmin, $ymin,<br />
$xmax, $ymax,<br />
grid => [$xrange,$yrange],<br />
axes => [0,0],<br />
size => [$xsize,$ysize],<br />
);<br />
<br />
# Add three functions to the graph. The language used in specifying plots is<br />
# described in the PGgraphmacros.pl docs. When a MathObject is used in double-<br />
# quotes, it is stringified into the quasi-TI notation that WeBWorK uses.<br />
plot_functions($graph,<br />
"$horiz_line for x in [0,3] using color:red and weight:2",<br />
"$diag_line for x in [3,5] using color:red and weight:2",<br />
"$par for x in [5,9] using color:red and weight:2",<br />
);<br />
<br />
# This changes how MathObjects are stringified. Instead of quasi-TI syntax,<br />
# we switch to TeX stringification.<br />
Context()->texStrings;<br />
<br />
# A BEGIN_TEXT...END_TEXT block is replaced by the preprocessor with:<br />
# TEXT(EV3(<<'END_TEXT'));<br />
# ...<br />
# END_TEXT<br />
# The <<'END_TEXT' part is the beginning of a Perl here document. Anyway, this<br />
# is just a convenience function, so you don't have to type that whole thing.<br />
# Basically whenever you see BEGIN_TEXT, you can read it as<br />
# TEXT(EV3(<<'END_TEXT'));<br />
# <br />
# TEXT() is the basic macro that outputs (well, accumulates actually) problem<br />
# "text", which can be HTML of TeX depending on the display mode.<br />
# <br />
# EV3() is a macro that interpretes it's contents according to these rules:<br />
# * Perl variables are evaluated in double-quoted string context. That is,<br />
# they get stringified.<br />
# * \{ EXPR \} blocks are replaced by the result of evaluating the perl code<br />
# inside.<br />
# * \( TEX \) blocks are replaced by equations described by the TEX code<br />
# within. Depending on the display mode, this can be plain text, an image, a<br />
# jsMath block, or raw TeX.<br />
# * \[ TEX \] blocks are treated similarly to \( TEX \) blocks, except that<br />
# the display math is used instead of inline math.<br />
# <br />
# In the original version of this problem, there was one BEGIN_TEXT/END_TEXT<br />
# block, but because I have to comment, I'm going to split it up into multiple<br />
# blocks.<br />
<br />
# beginproblem() prints the point value of the problem, the beginning of the<br />
# HTML form (in HTML-based display modes), and other header-type stuff.<br />
BEGIN_TEXT<br />
\{ beginproblem() \}<br />
END_TEXT<br />
<br />
# We use our textbook_ref_exact() macro to print "From Rogawski ET, section 3.1<br />
# problem 11".<br />
BEGIN_TEXT<br />
\{ textbook_ref_exact("Rogawski ET", "3.1","11") \}<br />
END_TEXT<br />
# $PAR is a double-line break. It contains &lt;P&gt; in HTML-based modes and \par in<br />
# TeX mode. Note the use of \( ... \) to typeset f(x).<br />
BEGIN_TEXT<br />
$PAR<br />
Let \( f(x) \) be the function whose graph is shown below.<br />
END_TEXT<br />
<br />
# We insert the graph that we generated before. insertGraph() actually generates<br />
# the image, and it returns the pathname of the image. image() takes that image<br />
# and actually generates code needed to place the image in the output. These<br />
# macros are in dangerousMacros.pl, which is always loaded. Documentation at:<br />
# <http://devel.webwork.rochester.edu/doc/cvs/pg_HEAD/macros/dangerousMacros.pl.html><br />
BEGIN_TEXT<br />
$PAR<br />
\{ image(insertGraph($graph)) \}<br />
END_TEXT<br />
<br />
# Now we ask the question.<br />
BEGIN_TEXT<br />
$PAR<br />
Determine \( f'(a) \) for \( a = 1,2,4,7 \).<br />
END_TEXT<br />
<br />
# And generate the answer blanks. $BR is a single-line break.<br />
BEGIN_TEXT<br />
$BR<br />
\( f'(1) = \) \{ans_rule()\}<br />
$BR<br />
\( f'(2) = \) \{ans_rule()\}<br />
$BR<br />
\( f'(4) = \) \{ans_rule()\}<br />
$BR<br />
\( f'(7) = \) \{ans_rule()\}<br />
END_TEXT<br />
<br />
# Switch back to normal strings now that we're done with the text block.<br />
Context()->normalStrings;<br />
<br />
# The ANS() macro takes an "answer evaluator" as its argument. An answer<br />
# evaluator is a perl function that gets passed the student's answer and<br />
# determines if it is correct or not. We don't have to write them ourselves,<br />
# because MathObjects know how to generate them, using the ->cmp method. These<br />
# ANS() calls must be in the same order as the ans_rule() calls above.<br />
ANS(Real(0)->cmp);<br />
ANS(Real(0)->cmp);<br />
ANS($slope->cmp);<br />
ANS(Real(0)->cmp);<br />
<br />
# Switch back to TeX stringification.<br />
Context()->texStrings;<br />
<br />
# SOLUTION() works like TEXT() except that it's only shown if the "show<br />
# solutions" flag is given. $SOL evaluates to "Solution: " in bold. Note the<br />
# MathObjects embedded in math expressions in the solution. Remember that they<br />
# are stringifying to their TeX representations.<br />
SOLUTION(EV3(<<'END_SOLUTION'));<br />
$PAR<br />
$SOL<br />
Remember that the value of the derivative of \( f \) at \( x=a \) can be<br />
interpreted as the slope of the line tangent to the graph of \( y = f(x) \) at<br />
\( x=a \). From the figure, we see that the graph of \( y = f(x) \) is a <br />
horizontal line (that is, a line with zero slope) on the interval <br />
\( 0 \le x \le 3 \). Accordingly, \( f'(1) = f'(2) = 0 \). On the interval <br />
\( 3 \le x \le 5 \), the graph of \( y = f(x) \) is a line of slope <br />
\( $slope \); thus, \( f'(4) = $slope \). Finally, the line tangent to the <br />
graph of \( y = f(x) \) at \( x=7 \) is horizontal, so \( f'(7) = 0 \).<br />
END_SOLUTION<br />
<br />
# This finishes everything up. It should always be the last executable line in<br />
# the file.<br />
[[Category:Authors]]</div>Xiong Chiamiovhttps://webwork.maa.org/mediawiki_new/index.php?title=SamsExampleProblem&diff=3937SamsExampleProblem2008-08-20T17:48:22Z<p>Xiong Chiamiov: remove extra line break in middle of sentance</p>
<hr />
<div> <br />
# PG problems are essentially Perl source files, with one exception: Perl<br />
# backslashes (\) are replaced by double-tildes (~~) since TeX uses<br />
# backslashes. For more about the format of PG files, consult the Translator.pm<br />
# documentation at:<br />
# <http://devel.webwork.rochester.edu/doc/cvs/pg_HEAD/lib/WeBWorK/PG/Translator.pm.html#translate><br />
<br />
# The first section in this file is a list of tags for the database problem<br />
# library project. For more about the tagging format, look at:<br />
# <http://hobbes.la.asu.edu/webwork-stuff/Tagging.html><br />
<br />
##DESCRIPTION<br />
## Plots a piecewise function made up of a horizontal line, a diagonal line, and<br />
## a parabola and asks the student to determine the derivative at various<br />
## interesting points.<br />
##ENDDESCRIPTION<br />
## DBsubject('Calculus')<br />
## DBchapter('Limits and Derivatives')<br />
## DBsection('Definition of the Derivative')<br />
## KEYWORDS('calculus', 'derivatives', 'slope')<br />
## TitleText1('Calculus')<br />
## EditionText1('1')<br />
## AuthorText1('Rogawski')<br />
## Section1('3.1')<br />
## Problem1('11')<br />
## Author('Sam Hathaway')<br />
## Institution('W.H.Freeman')<br />
<br />
# The DOCUMENT() call sets up initial values for PG internals. It should always<br />
# be the first executable line in the problem.<br />
DOCUMENT();<br />
<br />
# loadMacros() calls load macro files (which are Perl source files) into the<br />
# problem environment. These first three files are required by all problems.<br />
# Documentation:<br />
# <http://devel.webwork.rochester.edu/doc/cvs/pg_HEAD/macros/PG.pl.html><br />
# <http://devel.webwork.rochester.edu/doc/cvs/pg_HEAD/macros/PGbasicmacros.pl.html><br />
# <http://devel.webwork.rochester.edu/doc/cvs/pg_HEAD/macros/PGanswermacros.pl.html><br />
loadMacros("PG.pl","PGbasicmacros.pl","PGanswermacros.pl");<br />
<br />
# Parser.pl is the main macro file for MathObjects. This file defines macros<br />
# such as Real() and Formula(). You'll load it in pretty much all problems.<br />
# Parser docs are available at:<br />
# <http://devel.webwork.rochester.edu/twiki/bin/view/Webwork/MathObjects><br />
loadMacros("Parser.pl");<br />
<br />
# This is our macro file that provides the textbook_ref_exact() and<br />
# textbook_ref_corr() macros. You'll load it in all problems.<br />
loadMacros("freemanMacros.pl");<br />
<br />
# This macro file contains the ceil(), floor(), max(), and (min) macros, which<br />
# we use in this problem. If you're not using macros from this package, you do<br />
# not need to load it.<br />
loadMacros("PGauxiliaryFunctions.pl");<br />
<br />
# This macro file contains the init_graph() and plot_functions() macros. We need<br />
# these to create the graph for this problem. Don't load this unless you need<br />
# it. Documentation at:<br />
# <http://devel.webwork.rochester.edu/doc/cvs/pg_HEAD/macros/PGgraphmacros.pl.html><br />
loadMacros("PGgraphmacros.pl");<br />
<br />
# These are the values in the book version of the problem. Note that they are<br />
# commented out.<br />
#$base = 1;<br />
#$rise = 2;<br />
#$vertex_y = -2.25;<br />
<br />
# Here are the randomized values. Each student will get a different (but<br />
# persistent) value from each of these calls.<br />
$base = random(1,3,1);<br />
$rise = random(1,2,1);<br />
$vertex_y = random(1,4,0.25)*list_random(-1,1);<br />
<br />
# Create a MathObject formula for the initial height of the first horizontal<br />
# line.<br />
$horiz_line = Formula($base);<br />
<br />
# Represent the slope of the diagonal line. Set the reduceConstants flag of the<br />
# MathObjects context to 0, so that "$rise/2" is not reduced.<br />
Context()->flags->set(reduceConstants=>0);<br />
$slope = Formula("$rise/2");<br />
<br />
# This is the formula for the diagonal line.<br />
$diag_line = Formula("$slope*(x-3)+$base");<br />
<br />
# This is the formula for the parabola.<br />
$par = Formula("-($vertex_y/4)(x-5)(x-9)+$base+$rise");<br />
<br />
# Get the y-value of the vertex of the porabola. We know that it occurs at x=7,<br />
# so we evaluate the $par formula with at x=7.<br />
$real_vertex = $par->eval(x=>7);<br />
<br />
# Now we set some temporary variables that we'll pass into init_graph below:<br />
<br />
# Minimum and maximum x and y values to graph.<br />
$xmin = -1;<br />
$ymin = min(-1, ceil($real_vertex)-1);<br />
$xmax = 9;<br />
$ymax = max(5, $base+$rise+1, floor($real_vertex)+1);<br />
<br />
# We want grid lines on each integer value, but we have to specify the total<br />
# number of grid lines on each axis, so we just use the x and y range.<br />
$xrange = $xmax-$xmin;<br />
$yrange = $ymax-$ymin;<br />
<br />
# Size of the graph in pixels.<br />
$xsize = $xrange*25;<br />
$ysize = $yrange*25;<br />
<br />
# init_graph returns a graph object that we can then add functions to.<br />
$graph = init_graph(<br />
$xmin, $ymin,<br />
$xmax, $ymax,<br />
grid => [$xrange,$yrange],<br />
axes => [0,0],<br />
size => [$xsize,$ysize],<br />
);<br />
<br />
# Add three functions to the graph. The language used in specifying plots is<br />
# described in the PGgraphmacros.pl docs. When a MathObject is used in double-<br />
# quotes, it is stringified into the quasi-TI notation that WeBWorK uses.<br />
plot_functions($graph,<br />
"$horiz_line for x in [0,3] using color:red and weight:2",<br />
"$diag_line for x in [3,5] using color:red and weight:2",<br />
"$par for x in [5,9] using color:red and weight:2",<br />
);<br />
<br />
# This changes how MathObjects are stringified. Instead of quasi-TI syntax,<br />
# we switch to TeX stringification.<br />
Context()->texStrings;<br />
<br />
# A BEGIN_TEXT...END_TEXT block is replaced by the preprocessor with:<br />
# TEXT(EV3(<<'END_TEXT'));<br />
# ...<br />
# END_TEXT<br />
# The <<'END_TEXT' part is the beginning of a Perl here document. Anyway, this<br />
# is just a convenience function, so you don't have to type that whole thing.<br />
# Basically whenever you see BEGIN_TEXT, you can read it as<br />
# TEXT(EV3(<<'END_TEXT'));<br />
# <br />
# TEXT() is the basic macro that outputs (well, accumulates actually) problem<br />
# "text", which can be HTML of TeX depending on the display mode.<br />
# <br />
# EV3() is a macro that interpretes it's contents according to these rules:<br />
# * Perl variables are evaluated in double-quoted string context. That is,<br />
# they get stringified.<br />
# * \{ EXPR \} blocks are replaced by the result of evaluating the perl code<br />
# inside.<br />
# * \( TEX \) blocks are replaced by equations described by the TEX code<br />
# within. Depending on the display mode, this can be plain text, an image, a<br />
# jsMath block, or raw TeX.<br />
# * \[ TEX \] blocks are treated similarly to \( TEX \) blocks, except that<br />
# the display math is used instead of inline math.<br />
# <br />
# In the original version of this problem, there was one BEGIN_TEXT/END_TEXT<br />
# block, but because I have to comment, I'm going to split it up into multiple<br />
# blocks.<br />
<br />
# beginproblem() prints the point value of the problem, the beginning of the<br />
# HTML form (in HTML-based display modes), and other header-type stuff.<br />
BEGIN_TEXT<br />
\{ beginproblem() \}<br />
END_TEXT<br />
<br />
# We use our textbook_ref_exact() macro to print "From Rogawski ET, section 3.1<br />
# problem 11".<br />
BEGIN_TEXT<br />
\{ textbook_ref_exact("Rogawski ET", "3.1","11") \}<br />
END_TEXT<br />
# $PAR is a double-line break. It contains &lt;P&gt; in HTML-based modes and \par in<br />
# TeX mode. Note the use of \( ... \) to typeset f(x).<br />
BEGIN_TEXT<br />
$PAR<br />
Let \( f(x) \) be the function whose graph is shown below.<br />
END_TEXT<br />
<br />
# We insert the graph that we generated before. insertGraph() actually generates<br />
# the image, and it returns the pathname of the image. image() takes that image<br />
# and actually generates code needed to place the image in the output. These<br />
# macros are in dangerousMacros.pl, which is always loaded. Documentation at:<br />
# <http://devel.webwork.rochester.edu/doc/cvs/pg_HEAD/macros/dangerousMacros.pl.html><br />
BEGIN_TEXT<br />
$PAR<br />
\{ image(insertGraph($graph)) \}<br />
END_TEXT<br />
<br />
# Now we ask the question.<br />
BEGIN_TEXT<br />
$PAR<br />
Determine \( f'(a) \) for \( a = 1,2,4,7 \).<br />
END_TEXT<br />
<br />
# And generate the answer blanks. $BR is a single-line break.<br />
BEGIN_TEXT<br />
$BR<br />
\( f'(1) = \) \{ans_rule()\}<br />
$BR<br />
\( f'(2) = \) \{ans_rule()\}<br />
$BR<br />
\( f'(4) = \) \{ans_rule()\}<br />
$BR<br />
\( f'(7) = \) \{ans_rule()\}<br />
END_TEXT<br />
<br />
# Switch back to normal strings now that we're done with the text block.<br />
Context()->normalStrings;<br />
<br />
# The ANS() macro takes an "answer evaluator" as its argument. An answer<br />
# evaluator is a perl function that gets passed the student's answer and<br />
# determines if it is correct or not. We don't have to write them ourselves,<br />
# because MathObjects know how to generate them, using the ->cmp method. These<br />
# ANS() calls must be in the same order as the ans_rule() calls above.<br />
ANS(Real(0)->cmp);<br />
ANS(Real(0)->cmp);<br />
ANS($slope->cmp);<br />
ANS(Real(0)->cmp);<br />
<br />
# Switch back to TeX stringification.<br />
Context()->texStrings;<br />
<br />
# SOLUTION() works like TEXT() except that it's only shown if the "show<br />
# solutions" flag is given. $SOL evaluates to "Solution: " in bold. Note the<br />
# MathObjects embedded in math expressions in the solution. Remember that they<br />
# are stringifying to their TeX representations.<br />
SOLUTION(EV3(<<'END_SOLUTION'));<br />
$PAR<br />
$SOL<br />
Remember that the value of the derivative of \( f \) at \( x=a \) can be<br />
interpreted as the slope of the line tangent to the graph of \( y = f(x) \) at<br />
\( x=a \). From the figure, we see that the graph of \( y = f(x) \) is a <br />
horizontal line (that is, a line with zero slope) on the interval <br />
\( 0 \le x \le 3 \). Accordingly, \( f'(1) = f'(2) = 0 \). On the interval <br />
\( 3 \le x \le 5 \), the graph of \( y = f(x) \) is a line of slope <br />
\( $slope \); thus, \( f'(4) = $slope \). Finally, the line tangent to the <br />
graph of \( y = f(x) \) at \( x=7 \) is horizontal, so \( f'(7) = 0 \).<br />
END_SOLUTION<br />
<br />
# This finishes everything up. It should always be the last executable line in<br />
# the file.<br />
[[Category:Authors]]</div>Xiong Chiamiovhttps://webwork.maa.org/mediawiki_new/index.php?title=ContextModification1&diff=4309ContextModification12008-08-19T22:16:29Z<p>Xiong Chiamiov: Redirecting to Modifying contexts (advanced)</p>
<hr />
<div>#REDIRECT[[Modifying contexts (advanced)]]</div>Xiong Chiamiovhttps://webwork.maa.org/mediawiki_new/index.php?title=ContextList&diff=4307ContextList2008-08-19T22:14:55Z<p>Xiong Chiamiov: Redirecting to Introduction to contexts</p>
<hr />
<div>#REDIRECT[[Introduction to contexts]]</div>Xiong Chiamiovhttps://webwork.maa.org/mediawiki_new/index.php?title=SampleProblem2&diff=453SampleProblem22008-08-19T21:24:09Z<p>Xiong Chiamiov: commas separate individual quoted keywords</p>
<hr />
<div><h2>A Second WeBWorK Sample Problem: Problem Types</h2><br />
<p style="background-color:#eeeeee;border:black solid 1px;padding:3px;"><br />
<em>This sample problem shows how to write three commonly used problem types: formulas making use of more of the MathObjects Formula functionality, multiple choice, and string entry problems.</em><br />
</p><br />
<p><br />
Recall that a !WeBWorK PG file has five sections: (1)&nbsp;a <em>tagging and description section</em>, (2)&nbsp;an <em>initialization section</em>, (3)&nbsp;a <em>problem set-up section</em>, (4)&nbsp;a <em>text section</em>, and (5)&nbsp;an <em>answer and solution section</em>. These sections are shown below, and the parts of each of each that are related to the different problem types being discussed here are indicated.<br />
</p><br />
<p><br />
The sample file explained below is<br />
this file '''''(need attachment)'''''.<br />
</p><br />
<table cellspacing="0" cellpadding="2" border="0"><br />
<tr valign="top"><br />
<th> PG problem file </th><br />
<th> Explanation </th><br />
</tr><br />
<br />
<tr valign="top"><br />
<td style="background-color:#ddddff;border:black 1px dashed;"><br />
<pre><br />
# DESCRIPTION<br />
# A simple sample problem that illustrates <br />
# three common problem types.<br />
# WeBWorK problem written by Gavin LaRose, <br />
# &lt;glarose(at)umich(dot)edu&gt;<br />
# ENDDESCRIPTION<br />
<br />
## DBsubject('WeBWorK')<br />
## DBchapter('Demos')<br />
## DBsection('Problem')<br />
## KEYWORDS('')<br />
## TitleText1('')<br />
## EditionText1('')<br />
## AuthorText1('')<br />
## Section1('')<br />
## Problem1('')<br />
## Author('Gavin LaRose')<br />
## Institution('UMich')<br />
</pre><br />
</td><br />
<br />
<td style="background-color:#ccccff; padding:7px;"><br />
<p><br />
This is the <strong>tagging and description</strong> section of the problem.<br />
</p><br />
<p><br />
Recall that the tagging information exists to allow the problem to be easily indexed. Lists of tag values are on-line:<br />
[http://hobbes.la.asu.edu/Holt/chaps-and-secs.html current chapter and section names], and<br />
[http://hobbes.la.asu.edu/Holt/keywords.html current keywords]. The list of keywords should be comma separated and quoted (e.g., KEYWORDS('calculus','derivatives')).<br />
</p><br />
</td><br />
</tr><br />
<br />
<tr valign="top"><br />
<td style="background-color:#ddffdd;border:black 1px dashed;"><br />
<pre><br />
DOCUMENT();<br />
loadMacros(<br />
"PGstandard.pl",<br />
"MathObjects.pl",<br />
"PGchoicemacros.pl",<br />
);<br />
</pre><br />
</td><br />
<td style="background-color:#ccffcc;padding:7px;"><br />
<p><br />
This is the <strong>initialization section</strong> of the problem. To use the multiple choice object we use in this problem, we have to add <code>PGchoicemacros.pl</code> to the list of macros files that we load. <br />
</p><br />
</td><br />
</tr><br />
<br />
<tr valign="top"><br />
<td style="background-color:#ffffdd;border:black 1px dashed;"><br />
<pre><br />
# make sure we're in the context we want<br />
Context("Numeric");<br />
<br />
# INITIALIZATION FOR PART 1<br />
# set up a function for our formula problem.<br />
Context()-&gt;variables-&gt;add(t=&gt;'Real');<br />
$a = random(2,9,1);<br />
$func = Formula("cos($a t)");<br />
$funcDeriv = $func-&gt;D('t');<br />
$m = $funcDeriv-&gt;eval(t=&gt;2);<br />
$y0 = $func-&gt;eval(t=&gt;2);<br />
$line = Formula("$m (t - 2) + $y0");<br />
<br />
# INITIALIZATION FOR PART 2<br />
# set up for a multiple choice problem.<br />
$radio = new_multiple_choice();<br />
$radio-&gt;qa("This problem is", "easy");<br />
$radio-&gt;extra("very easy", "hard");<br />
$radio-&gt;makeLast("impossible");<br />
<br />
# INITIALIZATION FOR PART 3<br />
Context()-&gt;strings-&gt;add(True=&gt;{},False=&gt;{});<br />
$strAns = String('True');<br />
</pre><br />
</td><br />
<td style="background-color:#ffffcc;padding:7px;"><br />
<p><br />
This is the <strong>problem set-up section</strong> of the problem. <br />
</p><br />
<p><br />
For part 1, we define a function of the variable t. By default, <em>the only defined variable is x</em>, so we first add the real variable t to the Context. A list of [[ContextModification1|commonly used Context modifications]] is available. Then we define the function, find its derivative, and work out the equation of the tangent line to the function.<br />
</p><br />
<p><br />
Note: we're using a number of characteristics of Formulas here. <code>$f-&gt;D('t')</code> finds the derivative of <code>$f</code> with respect to <code>t</code>. Then, <code>$f-&gt;eval(t=&gt;2)</code> evaluates <code>$f</code> at the point <code>t=2</code>. Note that values must be specified for all variables when calling <code>eval</code>.<br />
</p><br />
<p><br />
For part 2, we define a radio object to include a multiple choice problem. The <code>$radio-&gt;qa("question","correctAnswer")</code> line gives the question and answer to the question. Then <code>$radio-&gt;extra("answer","answer",...)</code> defines extra (incorrect) answers for the problem. By using <code>$radio-&gt;makeLast("lastAnswer")</code> we can specify which answer is displayed last (all others will be presented in a random order). To make the correct answer be the last one, just call <code>$radio-&gt;makeLast("correctAnswer")</code> anytime after the initial <code>$radio-&gt;qa("question","correctAnswer")</code> call.<br />
</p><br />
<p><br />
For part 3, we are asking the student to enter a String answer. To avoid error messages we first add to the Context all valid strings (in this case, the strings "True" and "False"). Then we define a String object which gives the correct answer.<br />
</p><br />
</td><br />
</tr><br />
<tr valign="top"><br />
<td style="background-color:#ffdddd;border:black 1px dashed;"><br />
<pre><br />
TEXT(beginproblem());<br />
Context()-&gt;texStrings;<br />
BEGIN_TEXT<br />
${BBOLD}Part 1$EBOLD<br />
$BR<br />
Find the equation of the line tangent to <br />
\(f(t) = $func\) at \(t=2\).<br />
$BR<br />
\(y = \) \{ ans_rule(35) \} (note that this <br />
must be a function of \(t\).)<br />
<br />
$PAR<br />
${BBOLD}Part 2$EBOLD<br />
$BR<br />
\{ $radio->print_q() \}<br />
\{ $radio->print_a() \}<br />
<br />
$PAR<br />
${BBOLD}Part 3$EBOLD<br />
$BR<br />
(Enter True or False:&nbsp;) All instructors <br />
love WeBWorK. \{ ans_rule(6) \}<br />
<br />
END_TEXT<br />
Context()-&gt;normalStrings;<br />
</pre><br />
<td style="background-color:#ffcccc;padding:7px;"><br />
<p><br />
This is the <strong>text section</strong> of the problem. Note that we use a couple of formatting variables here: <code>${BBOLD}</code> begins a bold section of text, and <code>$EBOLD</code> ends it. <code>$BR</code> inserts a line break, and <code>$PAR</code> inserts a paragraph break.<br />
</p><br />
<p><br />
For Part 1, we display the equation in-line with <code>\(&nbsp;f(t)&nbsp;=&nbsp;$func\&nbsp;)</code> and then ask for the answer with an answer rule.<br />
</p><br />
<p><br />
For Part 2, we can just use the radio button object to print the question and options. Recall that <code>\{&nbsp;\}</code> executes code in the text section; <code>$radio-&gt;print_q()</code> (and <code>...print_a()</code>) are methods of the radio object that print the question and answers.<br />
</p><br />
<p><br />
For Part 3, we just ask a question and insert an answer rule.<br />
</p><br />
</td><br />
</tr><br />
<tr valign="top"><br />
<td style="background-color:#eeddff;border:black 1px dashed;"><br />
<pre><br />
ANS( $funcDeriv-&gt;cmp() );<br />
ANS( radio_cmp( $radio-&gt;correct_ans() ) );<br />
ANS( $strAns-&gt;cmp() );<br />
<br />
Context()-&gt;texStrings;<br />
SOLUTION(EV3(&lt;&lt;'END_SOLUTION'));<br />
$PAR SOLUTION $PAR<br />
${BBOLD}Part 1$EBOLD<br />
$BR<br />
The derivative of \(f(t) = $func\) is <br />
\(f'(t) = $funcDeriv\), so the slope of <br />
the line is \(f'(2) = $m\). Then when<br />
\(t = 2\) we have \(f(2) = $y0\), so the<br />
equation of the line is \(y = $line\).<br />
<br />
$PAR<br />
${BBOLD}Part 2$EBOLD<br />
$BR<br />
This problem is clearly easy.<br />
<br />
$PAR<br />
${BBOLD}Part 3$EBOLD<br />
$BR<br />
A careful study of one WeBWorK <br />
instructor showed that 100% of all<br />
respondents thought this statement<br />
was true.<br />
END_SOLUTION<br />
Context()-&gt;normalStrings;<br />
<br />
ENDDOCUMENT();<br />
</pre><br />
<td style="background-color:#eeccff;padding:7px;"><br />
<p><br />
This is the <strong>answer and solution</strong> section of the problem. Because there are three parts to the question, we have three <code>ANS()</code> calls. These evaluate the answer blanks in the order that they appeared in the problem.<br />
</p><br />
<p><br />
For the first part of the problem, we want to check that the student entered the right equation for the line. We therefore use the comparison method of the <code>$line</code> Formula we defined.<br />
</p><br />
<p><br />
For the second part of the problem we have to check that the student entered the correct (multiple-choice) answer. At the moment this requires that we use an <em>old-style answer checker</em>, <code>radio_cmp</code>. This just verifies that the answer that the student submitted is the same as the correct answer to the problem.<br />
</p><br />
<p><br />
For part 3, we just check that the answer the student submitted compares with the expected String.<br />
</p><br />
<p><br />
Finally, note that we can use any formatting that we use in the text section of the problem in the solution.<br />
</p><br />
</td><br />
</tr><br />
</table><br />
<br />
[[Category:Sample Problems]]</div>Xiong Chiamiovhttps://webwork.maa.org/mediawiki_new/index.php?title=SampleProblem3&diff=462SampleProblem32008-08-19T21:23:57Z<p>Xiong Chiamiov: commas separate individual quoted keywords</p>
<hr />
<div><h2>A Third WeBWorK Sample Problem: Graphics</h2><br />
<p style="background-color:#eeeeee;border:black solid 1px;padding:3px;"><br />
<em>This sample problem shows how to write problems that include simple dynamically generated graphs.</em><br />
</p><br />
<p><br />
Recall that a WeBWorK PG file has five sections: (1)&nbsp;a <em>tagging and description section</em>, (2)&nbsp;an <em>initialization section</em>, (3)&nbsp;a <em>problem set-up section</em>, (4)&nbsp;a <em>text section</em>, and (5)&nbsp;an <em>answer and solution section</em>. These sections are shown below, and the parts of each of each that are related to the different problem types being discussed here are indicated.<br />
</p><br />
<p><br />
The sample file explained below is<br />
this file '''''(need attachment)'''''.<br />
</p><br />
<table cellspacing="0" cellpadding="2" border="0"><br />
<tr valign="top"><br />
<th> PG problem file </th><br />
<th> Explanation </th><br />
</tr><br />
<tr valign="top"><br />
<td style="background-color:#ddddff;border:black 1px dashed;"><br />
<pre><br />
# DESCRIPTION<br />
# A simple sample problem that illustrates <br />
# how to include dynamically generated graphics<br />
# in a problem.<br />
# WeBWorK problem written by Gavin LaRose, <br />
# &lt;glarose(at)umich(dot)edu&gt;<br />
# ENDDESCRIPTION<br />
<br />
## DBsubject('WeBWorK')<br />
## DBchapter('Demos')<br />
## DBsection('Problem')<br />
## KEYWORDS('graphs')<br />
## TitleText1('')<br />
## EditionText1('')<br />
## AuthorText1('')<br />
## Section1('')<br />
## Problem1('')<br />
## Author('Gavin LaRose')<br />
## Institution('UMich')<br />
</pre><br />
</td><br />
<td style="background-color:#ccccff; padding:7px;"><br />
<p><br />
This is the <strong>tagging and description</strong> section of the problem.<br />
</p><br />
<p><br />
Recall that the tagging information exists to allow the problem to be easily indexed. Lists of tag values are on-line:<br />
[http://hobbes.la.asu.edu/Holt/chaps-and-secs.html current chapter and section names], and<br />
[http://hobbes.la.asu.edu/Holt/keywords.html current keywords]. The list of keywords should be comma separated and quoted (e.g., KEYWORDS('calculus','derivatives')).<br />
</p><br />
</td><br />
</tr><br />
<tr valign="top"><br />
<td style="background-color:#ddffdd;border:black 1px dashed;"><br />
<pre><br />
DOCUMENT();<br />
loadMacros(<br />
"PGstandard.pl",<br />
"MathObjects.pl",<br />
"PGgraphmacros.pl",<br />
);<br />
</pre><br />
</td><br />
<td style="background-color:#ccffcc;padding:7px;"><br />
<p><br />
This is the <strong>initialization section</strong> of the problem. Note that we need to include <code>PGgraphmacros.pl</code> to use graphs in the problem.<br />
</p><br />
</td><br />
</tr><br />
<tr valign="top"><br />
<td style="background-color:#ffffdd;border:black 1px dashed;"><br />
<pre><br />
# make sure we're in the context we want<br />
Context("Numeric");<br />
<br />
# we define a parabola to graph, making sure <br />
# that the x and y intercepts are nice<br />
$root1 = random(2,4,2);<br />
$root2 = $root1 + random(2,4,2);<br />
$func = Compute("-(1/8)(x-$root1)(x-$root2)");<br />
<br />
# the minimum and maximum y values this <br />
# reaches on the domain [-2,$root2+1] are<br />
$ymin = $func-&gt;eval(x=&gt;-2);<br />
$ymax = $func-&gt;eval(x=&gt;($root1+$root2)/2);<br />
<br />
# the domain is<br />
$xmin = -2;<br />
$xmax = $root2 + 1;<br />
# and the number of gridlines we graph<br />
$xgrid = $xmax + 2;<br />
$ygrid = $ymax - int($ymin) + 2;<br />
<br />
# now initialize the graph<br />
$graph = init_graph($xmin, int($ymin)-1, $xmax,<br />
$ymax+1, axes=&gt;[0,0], grid=&gt;[$xgrid,$ygrid],<br />
size=&gt;[150,150]);<br />
<br />
# and add the function to be graphed<br />
plot_functions( $graph, "$func for x in " .<br />
"&lt;$xmin,$xmax&gt; using color:blue " .<br />
"and weight:2");<br />
<br />
# for use below: the y-intercept is <br />
$yint = $func-&gt;eval(x=&gt;0);<br />
</pre><br />
</td><br />
<td style="background-color:#ffffcc;padding:7px;"><br />
<p><br />
This is the <strong>problem set-up section</strong> of the problem. <br />
</p><br />
<p><br />
We first define a MathObject to be the function we want. We will graph it on the domain <code>[-1, $root2+1]</code>, and so use the MathObject to figure out what the maximum and minimum values of the function are on that domain are (we need these to define the graph).<br />
</p><br />
<p><br />
Then we define the graph. This is first initialized; the required syntax is <code>init_graph(<i>xmin</i>,<i>ymin</i>,<i>xmax</i>,<i>ymax</i>)</code>, which will create a graph with the default options. In this case we have chosen to specify some specific options:<br />
</p><br />
<ul><br />
<li> <code>axes=&gt;[0,0]</code> specifies that the axes pass through the point (0,0), </li><br />
<li> <code>grid=&gt;[$xgrid,$ygrid]</code> specifies the number of evenly-spaced gridlines to be drawn on the graph, and </li><br />
<li> <code>size=&gt;[150,150]</code> specifies the size of the graph (in pixels). </li><br />
</ul><br />
<p><br />
Another commonly used option is<br />
</p><br />
<ul><br />
<li> <code>ticks=&gt;[<i>number</i>,<i>number</i>]</code>, which specifies the number of tick marks to put on the graph. (Obviously, this would be specified instead of <code>grid</code>.) </li><br />
</ul><br />
<p><br />
Then we add the function to the graph. The string that is used in this case always has the form indicated here: <code><i>function</i> for x in <i>range</i> using color:<i>color</i> and weight:<i>weight</i></code>. The <i>range</i> can be specified with standard interval notation: [0,3) will graph the function with a closed dot at the left endpoint and an open circle at the right. &lt;0,3&gt; omits points at the end of the function graph.<br />
</p><br />
<p><br />
One other note here: to break the string over multiple lines, we've used Perl's <em>concatenation</em> operator, <code>.</code> (a period): in Perl, saying<br />
</p><br />
<p style="margin-left:1.5em;"><br />
<code>$str="this&nbsp;and" . "that";</code><br /><br />
</p><br />
<p><br />
is the same as saying<br />
</p><br />
<p style="margin-left:1.5em;"><br />
<code>$str="this&nbsp;andthat";</code>.<br />
</p><br />
</td><br />
</tr><br />
<tr valign="top"><br />
<td style="background-color:#ffdddd;border:black 1px dashed;"><br />
<pre><br />
TEXT(beginproblem());<br />
Context()-&gt;texStrings;<br />
BEGIN_TEXT<br />
Consider the graph<br />
$BR<br />
$BCENTER<br />
\{ image( insertGraph($graph), tex_size=&gt;100,<br />
height=&gt;150, width=&gt;150,<br />
extra_html_tags=&gt;'alt="graph of a ' .<br />
'downward opening parabola with ' .<br />
'x-intercepts ' . $root1 . ' and ' .<br />
$root2 . ', and y-intercept ' .<br />
$yint . '."' ) \}<br />
$ECENTER<br />
<br />
$PAR<br />
What is the equation of this parabola?<br />
$BR<br />
\( y = \) \{ ans_rule(35) \}<br />
<br />
<br />
END_TEXT<br />
Context()-&gt;normalStrings;<br />
</pre><br />
<td style="background-color:#ffcccc;padding:7px;"><br />
<p><br />
This is the <strong>text section</strong> of the problem. Note that we've use a couple of [[FormatVariableList|formatting variables]] here: <code>$BR</code> to insert a line break, <code>$PAR</code> to insert a paragraph break, and <code>$BCENTER</code> and <code>$ECENTER</code> to begin and end a centered environment.<br />
</p><br />
<p><br />
The graph is inserted with the <code>image</code> macro; if we hadn't dynamically generated the graph (that is, if it were a static image), we could have just said <code>image(<i>imagename</i>)</code>. The <code>insertGraph</code> macro inserts the graph that we just generated. As with the <code>init_graph</code> call above, we could have just written <code>image(insertGraph($graph))</code>, but we've chosen to also include some useful options:<br />
</p><br />
<ul><br />
<li> <code>tex_size=&gt;100</code> gives a scaling to use when displaying the image in the hardcopy; 100 is 10% of the usual size; </li><br />
<li> <code>height=&gt;150, width=&gt;150</code> specify the height and width of the image. Because we specified these when we created the image, explicitly specifying them here means that the graph won't have to be scaled by the browser and will appear clearly without the student having to click on the graph to get a version in a separate window; and </li><br />
<li> <code>extra_html_tags=&gt;'alt="graph of..."'</code> is a rather messy way of making sure that there is intelligible alternate text for the image when it is displayed. This may be significant for accessibility issues. </li><br />
</ul><br />
</td><br />
</tr><br />
<tr valign="top"><br />
<td style="background-color:#eeddff;border:black 1px dashed;"><br />
<pre><br />
ANS( $func-&gt;cmp() );<br />
<br />
Context()-&gt;texStrings;<br />
SOLUTION(EV3(&lt;&lt;'END_SOLUTION'));<br />
$PAR SOLUTION $PAR<br />
Because we know that this is a parabola,<br />
and because we know that the x-intercepts<br />
are \(x = $root1\) and \(x = $root2\), <br />
we know that the equation of the function<br />
must be <br />
\[ y = a (x - $root1) (x - $root2) \]<br />
for some constant \(a\). The y-intercept<br />
is \(y = $yint\), which occurs when <br />
\(x = 0\), so we must have <br />
\(a($root1)($root2) = $yint\), so <br />
\(a = -\frac{1}{2}\), and our function is<br />
\[ y = $func. \]<br />
END_SOLUTION<br />
Context()-&gt;normalStrings;<br />
<br />
ENDDOCUMENT();<br />
</pre><br />
<td style="background-color:#eeccff;padding:7px;"><br />
<p><br />
This is the <strong>answer and solution</strong> section of the problem.<br />
</p><br />
<p><br />
Note that we use the same formatting conventions in the solution that are used in the text section of the problem.<br />
</p><br />
</td><br />
</tr><br />
</table><br />
<br />
[[Category:Sample Problems]]</div>Xiong Chiamiovhttps://webwork.maa.org/mediawiki_new/index.php?title=Old-style_example_template&diff=443Old-style example template2008-08-19T21:23:33Z<p>Xiong Chiamiov: commas separate individual quoted keywords</p>
<hr />
<div><h2>A First ~WeBWorK Sample Problem, Alternate Version</h2><br />
<br />
<p style="background-color:#eeeeee;border:black solid 1px;padding:3px;"><br />
<em>This sample problem shows the basic structure of a WeBWorK PG problem file and how it is constructed. This is different from the default first sample in that it uses "old-style" answer checkers instead of the more flexible [[MathObjectsOverview|MathObjects]].</em><br />
</p><br />
<p><br />
A standard WeBWorK PG file has five sections:<br />
</p><br />
<ol><br />
<li> A <em>tagging and description section</em>, that describes the problem for future users and authors,</li><br />
<li> An <em>initialization section</em>, that loads required macros for the problem,</li><br />
<li> A <em>problem set-up section</em> that sets variables specific to the problem,</li><br />
<li> A <em>text section</em>, that gives the text that is shown to the student, and</li><br />
<li> An <em>answer and solution section</em>, that specifies how the answer(s) to the problem is(are) marked for correctness, and gives a solution that may be shown to the student after the problem set is complete. </li><br />
</ol><br />
<p><br />
Below, the contents of the PG problem file are shown to the left, with a second column to the right that explains the different parts of the problem that are indicated above.<br />
</p><br />
<table cellspacing="0" cellpadding="2" border="0"><br />
<tr valign="top"><br />
<th> PG problem file </th><br />
<th> Explanation </th><br />
</tr><br />
<tr valign="top"><br />
<td style="background-color:#ddddff;border:black 1px dashed;"><br />
<pre><br />
# DESCRIPTION<br />
# A simple sample problem that asks students to <br />
# differentiate a trigonometric function.<br />
# WeBWorK problem written by Gavin LaRose, <br />
# &lt;glarose(at)umich(dot)edu&gt;<br />
# ENDDESCRIPTION<br />
<br />
## DBsubject('WeBWorK')<br />
## DBchapter('Demos')<br />
## DBsection('Problem')<br />
## KEYWORDS('')<br />
## TitleText1('')<br />
## EditionText1('')<br />
## AuthorText1('')<br />
## Section1('')<br />
## Problem1('')<br />
## Author('Gavin LaRose')<br />
## Institution('UMich')<br />
</pre><br />
</td><br />
<td style="background-color:#ccccff; padding:7px;"><br />
<p><br />
This is the <strong>tagging and description</strong> section of the problem. Note that any line that begins with a "#" character is a <em>comment</em> for other authors who read the problem, and is not interpreted by WeBWorK. <br />
</p><br />
<p><br />
The description is provided to give a quick summary of the problem so that someone reading it later knows what it does without having to read through all of the problem code.<br />
</p><br />
<p><br />
All of the tagging information exists to allow the problem to be easily indexed. Because this is a sample problem there isn't a textbook per se, and we've used some default tagging values. There is an on-line<br />
[http://hobbes.la.asu.edu/Holt/chaps-and-secs.html list of current chapter and section names] and a similar <br />
[http://hobbes.la.asu.edu/Holt/keywords.html list of keywords]. The list of keywords should be comma separated and quoted (e.g., KEYWORDS('calculus','derivatives')).<br />
</p><br />
</td><br />
</tr><br />
<tr valign="top"><br />
<td style="background-color:#ddffdd;border:black 1px dashed;"><br />
<pre><br />
DOCUMENT();<br />
loadMacros(<br />
"PGstandard.pl",<br />
"MathObjects.pl",<br />
"PGcourse.pl",<br />
);<br />
</pre><br />
</td><br />
<td style="background-color:#ccffcc;padding:7px;"><br />
<p><br />
This is the <strong>initialization section</strong> of the problem. The first executed line of the problem <strong>must</strong> be the <code>DOCUMENT();</code> command. Note that every command <em>must end with a semicolon</em>.<br />
</p><br />
<p><br />
The <code>loadMacros</code> command loads information that works behind the scenes. For our purposes we can usually just load the macros shown here and not worry about things further.<br />
</p><br />
</td><br />
</tr><br />
<tr valign="top"><br />
<td style="background-color:#ffffdd;border:black 1px dashed;"><br />
<pre><br />
# make sure we're in the context we want<br />
# Context("Numeric");<br />
<br />
$a = random(2,9,1);<br />
$trigFuncTeX = "\sin($a x)";<br />
$trigDeriv = "$a*cos($a*x)";<br />
$trigDerivTeX = "$a \cos($a x)";<br />
</pre><br />
</td><br />
<td style="background-color:#ffffcc;padding:7px;"><br />
<p><br />
This is the <strong>problem set-up section</strong> of the problem. Here we're using old-style answer checkers, and so aren't using [[MathObjectsOverview|MathObjects]]. This means we don't need to worry about the Context setting, so that line is commented out. <em>In many problems you will want to use MathObjects, however, so you will want to keep it in your files.</em><br />
</p><br />
<p><br />
The bulk of the set-up section defines variables that we use in the rest of the problem. All <em>scalar variables</em> are prefaced with a dollar sign: thus <code>$a</code> is a variable that has a (non-vector, non-array) value. Here we define three strings, one that specifies the TeX formula for the function that we're differentiating, one that gives the formula of the derivative in a form that will be understood by the old-style answer checker, and one that gives the TeX form of the derivative.<br />
</p><br />
</td><br />
</tr><br />
<tr valign="top"><br />
<td style="background-color:#ffdddd;border:black 1px dashed;"><br />
<pre><br />
TEXT(&beginproblem);<br />
# Context()-&gt;texStrings;<br />
BEGIN_TEXT<br />
Find the derivative of the function \(f(x) = $trigFuncTeX\).<br />
$PAR<br />
\(\frac{df}{dx} = \) \{ ans_rule(35) \}<br />
END_TEXT<br />
# Context()-&gt;normalStrings;<br />
</pre><br />
<td style="background-color:#ffcccc;padding:7px;"><br />
<p><br />
This is the <strong>text section</strong> of the problem. The <code>TEXT(&beginproblem);</code> line displays a header for the problem. We're not using MathObjects in this problem, so we don't need the <code>Context()-&gt;texStrings</code> line, but in most cases we will, so we've left that in as a comment here. Everything between the <code>BEGIN_TEXT</code> and <code>END_TEXT</code> lines (each of which must appear alone on a line) delimit the text that is shown to the student.<br />
</p><br />
<p><br />
Mathematical equations are delimited by <code>\(&nbsp;\)</code> (for inline equations) or <code>\[&nbsp;\]</code> (for displayed equations); in these contexts inserted text is assumed to be TeX code.<br />
</p><br />
<p><br />
There are a number of variables that set formatting: <code>$PAR</code> is a paragraph break (like <code>\par</code> in TeX). <br />
[[FormatVariableList|This page]] gives a list of variables like this. Finally, <code>\{&nbsp;\}</code> sets off <em>code that will be executed in the problem text</em>. Here, <code>ans_rule(35)</code> is a function that inserts an answer blank 35 characters long.<br />
</p><br />
</td><br />
</tr><br />
<tr valign="top"><br />
<td style="background-color:#eeddff;border:black 1px dashed;"><br />
<pre><br />
ANS( fun_cmp($trigDeriv) );<br />
<br />
# Context()-&gt;texStrings;<br />
SOLUTION(EV3(&lt;&lt;'END_SOLUTION'));<br />
$PAR SOLUTION $PAR<br />
We find the derivative to this using the <br />
chain rule. The inside function is \($a x\), <br />
so that its derivative is \($a\), and the <br />
outside function is \(\sin(x)\), which has <br />
derivative \(\cos(x)\). Thus the solution is<br />
\[ \frac{d}{dx} $trigFuncTeX = $trigDerivTeX. \]<br />
END_SOLUTION<br />
# Context()-&gt;normalStrings;<br />
<br />
ENDDOCUMENT();<br />
</pre><br />
<td style="background-color:#eeccff;padding:7px;"><br />
<p><br />
This is the <strong>answer and solution</strong> section of the problem. The problem answer is set by the <code>ANS(&nbsp;fun_cmp($trigDeriv)&nbsp;);</code> line, which simply says that the answer is marked by comparing the student's answer with the trigonometric function derivative that we defined before. The <code>fun_cmp</code> function is an "old-style" answer evaluator that checks a function. The other most common such answer evaluator is <code>num_cmp</code>, which checks a numerical answer.<br />
</p><br />
<p><br />
Then, we explain the solution to the student. This solution will show up when the student clicks the "show solution" checkbox after they've finished the problem set.<br />
</p><br />
<p><br />
The <code>ENDDOCUMENT();</code> command is the last command in the file.<br />
</p><br />
</td><br />
</tr><br />
</table><br />
<br />
[[Category:Sample Problems]]</div>Xiong Chiamiovhttps://webwork.maa.org/mediawiki_new/index.php?title=SampleProblem1&diff=437SampleProblem12008-08-19T21:23:01Z<p>Xiong Chiamiov: commas separate individual quoted keywords</p>
<hr />
<div><h2>A First WeBWorK Sample Problem</h2><br />
<p style="background-color:#eeeeee;border:black solid 1px;padding:3px;"><br />
<em>This sample problem shows the basic structure of a WeBWorK PG problem file and how it is constructed.</em><br />
</p><br />
<p><br />
A standard WeBWorK PG file has five sections:<br />
</p><br />
<ol><br />
<li> A <em>tagging and description section</em>, that describes the problem for future users and authors,</li><br />
<li> An <em>initialization section</em>, that loads required macros for the problem,</li><br />
<li> A <em>problem set-up section</em> that sets variables specific to the problem,</li><br />
<li> A <em>text section</em>, that gives the text that is shown to the student, and</li><br />
<li> An <em>answer and solution section</em>, that specifies how the answer(s) to the problem is(are) marked for correctness, and gives a solution that may be shown to the student after the problem set is complete. </li><br />
</ol><br />
<p><br />
The sample file attached to this page shows this; below the file is shown to the left, with a second column on its right that explains the different parts of the problem that are indicated above.<br />
</p><br />
<table cellspacing="0" cellpadding="2" border="0"><br />
<tr valign="top"><br />
<th> PG problem file </th><br />
<th> Explanation </th><br />
</tr><br />
<tr valign="top"><br />
<td style="background-color:#ddddff;border:black 1px dashed;"><br />
<pre><br />
# DESCRIPTION<br />
# A simple sample problem that asks students to <br />
# differentiate a trigonometric function.<br />
# WeBWorK problem written by Gavin LaRose, <br />
# &lt;glarose(at)umich(dot)edu&gt;<br />
# ENDDESCRIPTION<br />
<br />
## DBsubject('WeBWorK')<br />
## DBchapter('Demos')<br />
## DBsection('Problem')<br />
## KEYWORDS('')<br />
## TitleText1('')<br />
## EditionText1('')<br />
## AuthorText1('')<br />
## Section1('')<br />
## Problem1('')<br />
## Author('Gavin LaRose')<br />
## Institution('UMich')<br />
</pre><br />
</td><br />
<td style="background-color:#ccccff; padding:7px;"><br />
<p><br />
This is the <strong>tagging and description</strong> section of the problem. Note that any line that begins with a "#" character is a <em>comment</em> for other authors who read the problem, and is not interpreted by !WeBWorK. <br />
</p><br />
<p><br />
The description is provided to give a quick summary of the problem so that someone reading it later knows what it does without having to read through all of the problem code.<br />
</p><br />
<p><br />
All of the tagging information exists to allow the problem to be easily indexed. Because this is a sample problem there isn't a textbook per se, and we've used some default tagging values. There is an on-line<br />
[http://hobbes.la.asu.edu/Holt/chaps-and-secs.html list of current chapter and section names] and a similar <br />
[http://hobbes.la.asu.edu/Holt/keywords.html list of keywords]. The list of keywords should be comma separated and quoted (e.g., KEYWORDS('calculus','derivatives')).<br />
</p><br />
</td><br />
</tr><br />
<tr valign="top"><br />
<td style="background-color:#ddffdd;border:black 1px dashed;"><br />
<pre><br />
DOCUMENT();<br />
loadMacros(<br />
"PGstandard.pl",<br />
"MathObjects.pl",<br />
);<br />
</pre><br />
</td><br />
<td style="background-color:#ccffcc;padding:7px;"><br />
<p><br />
This is the <strong>initialization section</strong> of the problem. The first executed line of the problem <strong>must</strong> be the <code>DOCUMENT();</code> command. Note that every command <em>must end with a semicolon</em>.<br />
</p><br />
<p><br />
The <code>loadMacros</code> command loads information that works behind the scenes. For our purposes we can usually just load the macros shown here and not worry about things further.<br />
</p><br />
</td><br />
</tr><br />
<tr valign="top"><br />
<td style="background-color:#ffffdd;border:black 1px dashed;"><br />
<pre><br />
# make sure we're in the context we want<br />
Context("Numeric");<br />
<br />
$a = random(2,9,1);<br />
$trigFunc = Formula("sin($a x)");<br />
$trigDeriv = $trigFunc-&gt;D();<br />
</pre><br />
</td><br />
<td style="background-color:#ffffcc;padding:7px;"><br />
<p><br />
This is the <strong>problem set-up section</strong> of the problem. <code>Context("Numeric");</code> sets the "context", which determines how variables are interpreted. Contexts and context explanations are given on [[ContextList|this help page]].<br />
</p><br />
<p><br />
The bulk of the set-up section defines variables that we use in the rest of the problem. All <em>scalar variables</em> are prefaced with a dollar sign: thus <code>$a</code> is a variable that has a (non-vector, non-array) value. We also define <code>$trigFunc</code> to be a [[MathObjectsOverview|MathObject]] <code>Formula</code>, which means that it knows things about itself, in particular, how to find its own derivative, which we find with the expression <code>$trigFunc-&gt;D()</code>.<br />
</p><br />
</td><br />
</tr><br />
<tr valign="top"><br />
<td style="background-color:#ffdddd;border:black 1px dashed;"><br />
<pre><br />
TEXT(beginproblem());<br />
Context()-&gt;texStrings;<br />
BEGIN_TEXT<br />
Find the derivative of the function \(f(x) = $trigFunc\).<br />
$PAR<br />
\(\frac{df}{dx} = \) \{ ans_rule(35) \}<br />
END_TEXT<br />
Context()-&gt;normalStrings;<br />
</pre><br />
<td style="background-color:#ffcccc;padding:7px;"><br />
<p><br />
This is the <strong>text section</strong> of the problem. The <code>TEXT(beginproblem());</code> line displays a header for the problem, and the <code>Context()-&gt;texStrings</code> line sets how formulas are displayed in the text, and we reset this after the text section. Everything between the <code>BEGIN_TEXT</code> and <code>END_TEXT</code> lines (each of which must appear alone on a line) is shown to the student.<br />
</p><br />
<p><br />
Mathematical equations are delimited by <code>\(&nbsp;\)</code> (for inline equations) or <code>\[&nbsp;\]</code> (for displayed equations); in these contexts inserted text is assumed to be TeX code.<br />
</p><br />
<p><br />
There are a number of variables that set formatting: <code>$PAR</code> is a paragraph break (like <code>\par</code> in TeX). <br />
[[FormatVariableList|This page]] gives a list of variables like this. Finally, <code>\{&nbsp;\}</code> sets off <em>code that will be executed in the problem text</em>. Here, <code>ans_rule(35)</code> is a function that inserts an answer blank 35 characters wide.<br />
</p><br />
</td><br />
</tr><br />
<tr valign="top"><br />
<td style="background-color:#eeddff;border:black 1px dashed;"><br />
<pre><br />
ANS( $trigDeriv-&gt;cmp() );<br />
<br />
Context()-&gt;texStrings;<br />
SOLUTION(EV3(&lt;&lt;'END_SOLUTION'));<br />
$PAR SOLUTION $PAR<br />
We find the derivative to this using the <br />
chain rule. The inside function is \($a x\), <br />
so that its derivative is \($a\), and the <br />
outside function is \(\sin(x)\), which has <br />
derivative \(\cos(x)\). Thus the solution is<br />
\[ \frac{d}{dx} $trigFunc = $trigDeriv. \]<br />
END_SOLUTION<br />
Context()-&gt;normalStrings;<br />
<br />
ENDDOCUMENT();<br />
</pre><br />
<td style="background-color:#eeccff;padding:7px;"><br />
<p><br />
This is the <strong>answer and solution</strong> section of the problem. The problem answer is set by the <code>ANS(&nbsp;$trigDeriv-&gt;cmp()&nbsp;);</code> line, which simply says that the answer is marked by comparing the student's answer with the trigonometric function derivative that we defined before.<br />
</p><br />
<p><br />
Then, we explain the solution to the student. This solution will show up when the student clicks the "show solution" checkbox after they've finished the problem set.<br />
</p><br />
<p><br />
The <code>ENDDOCUMENT();</code> command is the last command in the file.<br />
</p><br />
</td><br />
</tr><br />
</table><br />
<br />
[[Category:Sample Problems]]</div>Xiong Chiamiovhttps://webwork.maa.org/mediawiki_new/index.php?title=SampleProblem1&diff=436SampleProblem12008-08-12T21:04:25Z<p>Xiong Chiamiov: fix typo (wrong word)</p>
<hr />
<div><h2>A First WeBWorK Sample Problem</h2><br />
<p style="background-color:#eeeeee;border:black solid 1px;padding:3px;"><br />
<em>This sample problem shows the basic structure of a WeBWorK PG problem file and how it is constructed.</em><br />
</p><br />
<p><br />
A standard WeBWorK PG file has five sections:<br />
</p><br />
<ol><br />
<li> A <em>tagging and description section</em>, that describes the problem for future users and authors,</li><br />
<li> An <em>initialization section</em>, that loads required macros for the problem,</li><br />
<li> A <em>problem set-up section</em> that sets variables specific to the problem,</li><br />
<li> A <em>text section</em>, that gives the text that is shown to the student, and</li><br />
<li> An <em>answer and solution section</em>, that specifies how the answer(s) to the problem is(are) marked for correctness, and gives a solution that may be shown to the student after the problem set is complete. </li><br />
</ol><br />
<p><br />
The sample file attached to this page shows this; below the file is shown to the left, with a second column on its right that explains the different parts of the problem that are indicated above.<br />
</p><br />
<table cellspacing="0" cellpadding="2" border="0"><br />
<tr valign="top"><br />
<th> PG problem file </th><br />
<th> Explanation </th><br />
</tr><br />
<tr valign="top"><br />
<td style="background-color:#ddddff;border:black 1px dashed;"><br />
<pre><br />
# DESCRIPTION<br />
# A simple sample problem that asks students to <br />
# differentiate a trigonometric function.<br />
# WeBWorK problem written by Gavin LaRose, <br />
# &lt;glarose(at)umich(dot)edu&gt;<br />
# ENDDESCRIPTION<br />
<br />
## DBsubject('WeBWorK')<br />
## DBchapter('Demos')<br />
## DBsection('Problem')<br />
## KEYWORDS('')<br />
## TitleText1('')<br />
## EditionText1('')<br />
## AuthorText1('')<br />
## Section1('')<br />
## Problem1('')<br />
## Author('Gavin LaRose')<br />
## Institution('UMich')<br />
</pre><br />
</td><br />
<td style="background-color:#ccccff; padding:7px;"><br />
<p><br />
This is the <strong>tagging and description</strong> section of the problem. Note that any line that begins with a "#" character is a <em>comment</em> for other authors who read the problem, and is not interpreted by !WeBWorK. <br />
</p><br />
<p><br />
The description is provided to give a quick summary of the problem so that someone reading it later knows what it does without having to read through all of the problem code.<br />
</p><br />
<p><br />
All of the tagging information exists to allow the problem to be easily indexed. Because this is a sample problem there isn't a textbook per se, and we've used some default tagging values. There is an on-line<br />
[http://hobbes.la.asu.edu/Holt/chaps-and-secs.html list of current chapter and section names] and a similar <br />
[http://hobbes.la.asu.edu/Holt/keywords.html list of keywords]. The list of keywords should be comma separated and quoted (e.g., KEYWORDS('calculus,derivatives')).<br />
</p><br />
</td><br />
</tr><br />
<tr valign="top"><br />
<td style="background-color:#ddffdd;border:black 1px dashed;"><br />
<pre><br />
DOCUMENT();<br />
loadMacros(<br />
"PGstandard.pl",<br />
"MathObjects.pl",<br />
);<br />
</pre><br />
</td><br />
<td style="background-color:#ccffcc;padding:7px;"><br />
<p><br />
This is the <strong>initialization section</strong> of the problem. The first executed line of the problem <strong>must</strong> be the <code>DOCUMENT();</code> command. Note that every command <em>must end with a semicolon</em>.<br />
</p><br />
<p><br />
The <code>loadMacros</code> command loads information that works behind the scenes. For our purposes we can usually just load the macros shown here and not worry about things further.<br />
</p><br />
</td><br />
</tr><br />
<tr valign="top"><br />
<td style="background-color:#ffffdd;border:black 1px dashed;"><br />
<pre><br />
# make sure we're in the context we want<br />
Context("Numeric");<br />
<br />
$a = random(2,9,1);<br />
$trigFunc = Formula("sin($a x)");<br />
$trigDeriv = $trigFunc-&gt;D();<br />
</pre><br />
</td><br />
<td style="background-color:#ffffcc;padding:7px;"><br />
<p><br />
This is the <strong>problem set-up section</strong> of the problem. <code>Context("Numeric");</code> sets the "context", which determines how variables are interpreted. Contexts and context explanations are given on [[ContextList|this help page]].<br />
</p><br />
<p><br />
The bulk of the set-up section defines variables that we use in the rest of the problem. All <em>scalar variables</em> are prefaced with a dollar sign: thus <code>$a</code> is a variable that has a (non-vector, non-array) value. We also define <code>$trigFunc</code> to be a [[MathObjectsOverview|MathObject]] <code>Formula</code>, which means that it knows things about itself, in particular, how to find its own derivative, which we find with the expression <code>$trigFunc-&gt;D()</code>.<br />
</p><br />
</td><br />
</tr><br />
<tr valign="top"><br />
<td style="background-color:#ffdddd;border:black 1px dashed;"><br />
<pre><br />
TEXT(beginproblem());<br />
Context()-&gt;texStrings;<br />
BEGIN_TEXT<br />
Find the derivative of the function \(f(x) = $trigFunc\).<br />
$PAR<br />
\(\frac{df}{dx} = \) \{ ans_rule(35) \}<br />
END_TEXT<br />
Context()-&gt;normalStrings;<br />
</pre><br />
<td style="background-color:#ffcccc;padding:7px;"><br />
<p><br />
This is the <strong>text section</strong> of the problem. The <code>TEXT(beginproblem());</code> line displays a header for the problem, and the <code>Context()-&gt;texStrings</code> line sets how formulas are displayed in the text, and we reset this after the text section. Everything between the <code>BEGIN_TEXT</code> and <code>END_TEXT</code> lines (each of which must appear alone on a line) is shown to the student.<br />
</p><br />
<p><br />
Mathematical equations are delimited by <code>\(&nbsp;\)</code> (for inline equations) or <code>\[&nbsp;\]</code> (for displayed equations); in these contexts inserted text is assumed to be TeX code.<br />
</p><br />
<p><br />
There are a number of variables that set formatting: <code>$PAR</code> is a paragraph break (like <code>\par</code> in TeX). <br />
[[FormatVariableList|This page]] gives a list of variables like this. Finally, <code>\{&nbsp;\}</code> sets off <em>code that will be executed in the problem text</em>. Here, <code>ans_rule(35)</code> is a function that inserts an answer blank 35 characters wide.<br />
</p><br />
</td><br />
</tr><br />
<tr valign="top"><br />
<td style="background-color:#eeddff;border:black 1px dashed;"><br />
<pre><br />
ANS( $trigDeriv-&gt;cmp() );<br />
<br />
Context()-&gt;texStrings;<br />
SOLUTION(EV3(&lt;&lt;'END_SOLUTION'));<br />
$PAR SOLUTION $PAR<br />
We find the derivative to this using the <br />
chain rule. The inside function is \($a x\), <br />
so that its derivative is \($a\), and the <br />
outside function is \(\sin(x)\), which has <br />
derivative \(\cos(x)\). Thus the solution is<br />
\[ \frac{d}{dx} $trigFunc = $trigDeriv. \]<br />
END_SOLUTION<br />
Context()-&gt;normalStrings;<br />
<br />
ENDDOCUMENT();<br />
</pre><br />
<td style="background-color:#eeccff;padding:7px;"><br />
<p><br />
This is the <strong>answer and solution</strong> section of the problem. The problem answer is set by the <code>ANS(&nbsp;$trigDeriv-&gt;cmp()&nbsp;);</code> line, which simply says that the answer is marked by comparing the student's answer with the trigonometric function derivative that we defined before.<br />
</p><br />
<p><br />
Then, we explain the solution to the student. This solution will show up when the student clicks the "show solution" checkbox after they've finished the problem set.<br />
</p><br />
<p><br />
The <code>ENDDOCUMENT();</code> command is the last command in the file.<br />
</p><br />
</td><br />
</tr><br />
</table><br />
<br />
[[Category:Sample Problems]]</div>Xiong Chiamiovhttps://webwork.maa.org/mediawiki_new/index.php?title=SampleProblem1&diff=435SampleProblem12008-08-12T21:01:57Z<p>Xiong Chiamiov: </p>
<hr />
<div><h2>A First WeBWorK Sample Problem</h2><br />
<p style="background-color:#eeeeee;border:black solid 1px;padding:3px;"><br />
<em>This sample problem shows the basic structure of a WeBWorK PG problem file and how it is constructed.</em><br />
</p><br />
<p><br />
A standard WeBWorK PG file has five sections:<br />
</p><br />
<ol><br />
<li> A <em>tagging and description section</em>, that describes the problem for future users and authors,</li><br />
<li> An <em>initialization section</em>, that loads required macros for the problem,</li><br />
<li> A <em>problem set-up section</em> that sets variables specific to the problem,</li><br />
<li> A <em>text section</em>, that gives the text that is shown to the student, and</li><br />
<li> An <em>answer and solution section</em>, that specifies how the answer(s) to the problem is(are) marked for correctness, and gives a solution that may be shown to the student after the problem set is complete. </li><br />
</ol><br />
<p><br />
The sample file attached to this page shows this; below the file is shown to the left, with a second column on its right that explains the different parts of the problem that are indicated above.<br />
</p><br />
<table cellspacing="0" cellpadding="2" border="0"><br />
<tr valign="top"><br />
<th> PG problem file </th><br />
<th> Explanation </th><br />
</tr><br />
<tr valign="top"><br />
<td style="background-color:#ddddff;border:black 1px dashed;"><br />
<pre><br />
# DESCRIPTION<br />
# A simple sample problem that asks students to <br />
# differentiate a trigonometric function.<br />
# WeBWorK problem written by Gavin LaRose, <br />
# &lt;glarose(at)umich(dot)edu&gt;<br />
# ENDDESCRIPTION<br />
<br />
## DBsubject('WeBWorK')<br />
## DBchapter('Demos')<br />
## DBsection('Problem')<br />
## KEYWORDS('')<br />
## TitleText1('')<br />
## EditionText1('')<br />
## AuthorText1('')<br />
## Section1('')<br />
## Problem1('')<br />
## Author('Gavin LaRose')<br />
## Institution('UMich')<br />
</pre><br />
</td><br />
<td style="background-color:#ccccff; padding:7px;"><br />
<p><br />
This is the <strong>tagging and description</strong> section of the problem. Note that any line that begins with a "#" character is a <em>comment</em> for other authors who read the problem, and is not interpreted by !WeBWorK. <br />
</p><br />
<p><br />
The description is provided to give a quick summary of the problem so that someone reading it later knows what it does without having to read through all of the problem code.<br />
</p><br />
<p><br />
All of the tagging information exists to allow the problem to be easily indexed. Because this is a sample problem there isn't a textbook per se, and we've used some default tagging values. There is an on-line<br />
[http://hobbes.la.asu.edu/Holt/chaps-and-secs.html list of current chapter and section names] and a similar <br />
[http://hobbes.la.asu.edu/Holt/keywords.html list of keywords]. The list of keywords should be comma separated and quoted (e.g., KEYWORDS('calculus,derivatives')).<br />
</p><br />
</td><br />
</tr><br />
<tr valign="top"><br />
<td style="background-color:#ddffdd;border:black 1px dashed;"><br />
<pre><br />
DOCUMENT();<br />
loadMacros(<br />
"PGstandard.pl",<br />
"MathObjects.pl",<br />
);<br />
</pre><br />
</td><br />
<td style="background-color:#ccffcc;padding:7px;"><br />
<p><br />
This is the <strong>initialization section</strong> of the problem. The first executed line of the problem <strong>must</strong> be the <code>DOCUMENT();</code> command. Note that every command <em>must end with a semicolon</em>.<br />
</p><br />
<p><br />
The <code>loadMacros</code> command loads information that works behind the scenes. For our purposes we can usually just load the macros shown here and not worry about things further.<br />
</p><br />
</td><br />
</tr><br />
<tr valign="top"><br />
<td style="background-color:#ffffdd;border:black 1px dashed;"><br />
<pre><br />
# make sure we're in the context we want<br />
Context("Numeric");<br />
<br />
$a = random(2,9,1);<br />
$trigFunc = Formula("sin($a x)");<br />
$trigDeriv = $trigFunc-&gt;D();<br />
</pre><br />
</td><br />
<td style="background-color:#ffffcc;padding:7px;"><br />
<p><br />
This is the <strong>problem set-up section</strong> of the problem. <code>Context("Numeric");</code> sets the "context", which determines how variables are interpreted. Contexts and context explanations are given on [[ContextList|this help page]].<br />
</p><br />
<p><br />
The bulk of the set-up section defines variables that we use in the rest of the problem. All <em>scalar variables</em> are prefaced with a dollar sign: thus <code>$a</code> is a variable that has a (non-vector, non-array) value. We also define <code>$trigFunc</code> to be a [[MathObjectsOverview|MathObject]] <code>Formula</code>, which means that it knows things about itself, in particular, how to find its own derivative, which we find with the expression <code>$trigFunc-&gt;D()</code>.<br />
</p><br />
</td><br />
</tr><br />
<tr valign="top"><br />
<td style="background-color:#ffdddd;border:black 1px dashed;"><br />
<pre><br />
TEXT(beginproblem());<br />
Context()-&gt;texStrings;<br />
BEGIN_TEXT<br />
Find the derivative of the function \(f(x) = $trigFunc\).<br />
$PAR<br />
\(\frac{df}{dx} = \) \{ ans_rule(35) \}<br />
END_TEXT<br />
Context()-&gt;normalStrings;<br />
</pre><br />
<td style="background-color:#ffcccc;padding:7px;"><br />
<p><br />
This is the <strong>text section</strong> of the problem. The <code>TEXT(beginproblem());</code> line displays a header for the problem, and the <code>Context()-&gt;texStrings</code> line sets how formulas are displayed in the text, and we reset this after the text section. Everything between the <code>BEGIN_TEXT</code> and <code>END_TEXT</code> lines (each of which must appear alone on a line) is shown to the student.<br />
</p><br />
<p><br />
Mathematical equations are delimited by <code>\(&nbsp;\)</code> (for inline equations) or <code>\[&nbsp;\]</code> (for displayed equations); in these contexts inserted text is assumed to be TeX code.<br />
</p><br />
<p><br />
There are a number of variables that set formatting: <code>$PAR</code> is a paragraph break (like <code>\par</code> in TeX). <br />
[[FormatVariableList|This page]] gives a list of variables like this. Finally, <code>\{&nbsp;\}</code> sets off <em>code that will be executed in the problem text</em>. Here, <code>ans_rule(35)</code> is a function that inserts an answer blank 35 characters line.<br />
</p><br />
</td><br />
</tr><br />
<tr valign="top"><br />
<td style="background-color:#eeddff;border:black 1px dashed;"><br />
<pre><br />
ANS( $trigDeriv-&gt;cmp() );<br />
<br />
Context()-&gt;texStrings;<br />
SOLUTION(EV3(&lt;&lt;'END_SOLUTION'));<br />
$PAR SOLUTION $PAR<br />
We find the derivative to this using the <br />
chain rule. The inside function is \($a x\), <br />
so that its derivative is \($a\), and the <br />
outside function is \(\sin(x)\), which has <br />
derivative \(\cos(x)\). Thus the solution is<br />
\[ \frac{d}{dx} $trigFunc = $trigDeriv. \]<br />
END_SOLUTION<br />
Context()-&gt;normalStrings;<br />
<br />
ENDDOCUMENT();<br />
</pre><br />
<td style="background-color:#eeccff;padding:7px;"><br />
<p><br />
This is the <strong>answer and solution</strong> section of the problem. The problem answer is set by the <code>ANS(&nbsp;$trigDeriv-&gt;cmp()&nbsp;);</code> line, which simply says that the answer is marked by comparing the student's answer with the trigonometric function derivative that we defined before.<br />
</p><br />
<p><br />
Then, we explain the solution to the student. This solution will show up when the student clicks the "show solution" checkbox after they've finished the problem set.<br />
</p><br />
<p><br />
The <code>ENDDOCUMENT();</code> command is the last command in the file.<br />
</p><br />
</td><br />
</tr><br />
</table><br />
<br />
[[Category:Sample Problems]]</div>Xiong Chiamiovhttps://webwork.maa.org/mediawiki_new/index.php?title=Basic_Perl_syntax&diff=3001Basic Perl syntax2008-08-12T20:15:49Z<p>Xiong Chiamiov: /* Constants */ add missing close quotes</p>
<hr />
<div>The PG Language is based on Perl. It helps to have a basic grasp of Perl before you start authoring PG problems. This article covers the minimum of Perl you need to know to work with PG.<br />
<br />
== Important changes from vanilla Perl ==<br />
<br />
If you already know Perl, this is all you need to know:<br />
<br />
Because backslashes have a special meaning within BEGIN_TEXT...END_TEXT blocks, backslashes are not used for their normal Perl meaning. Instead, ~~ (double-tilde):<br />
<br />
{|border="1"<br />
! Perl<br />
!PG<br />
|-<br />
|<br />
print "Hello, $name\n";<br />
|<br />
print "Hello, $name~~n";<br />
|-<br />
|<br />
$aref = \@array;<br />
$href = \%hash;<br />
$sref = \$scalar;<br />
|<br />
$aref = ~~@array;<br />
$href = ~~%hash;<br />
$sref = ~~$scalar;<br />
|}<br />
<br />
== Perl Syntax Overview ==<br />
<br />
=== Statements ===<br />
<br />
Each statement in Perl must end on a semicolon. Statements can be spread over several lines. Spacing and indentation is for the most part ignored by Perl and should be used to make the program more readable. (See the <code>&lt;&lt;EOF</code> construction for the one case where spacing can't be ignored.)<br />
<br />
$a = 1;<br />
Context("Numeric");<br />
<br />
=== Comment lines ===<br />
<br />
Comments start with # and continue to the end of the line.<br />
<br />
=== Data types ===<br />
<br />
==== Variables ====<br />
<br />
'''Scalar variable''' names start with a dollar sign (e.g. <code>$scalar_variable</code>). Scalar variables can contain an integer, a real number, a string or advanced types (pointers to objects).<br />
<br />
'''Array or list variable''' names start with an @ sign (e.g. <code>@list_variable</code>). Lists contain a sequence of scalar variables indexed by integers starting with zero. They have an implied order.<br />
<br />
'''Hash or associate array variable''' names start with a % sign (e.g. <code>%hash_variable</code>). Hashes also contain a set of scalar variables, but the indices can be any string, and they have no implied order. The hash is stored as key-value pairs.<br />
<br />
==== Constants ====<br />
<br />
A number: e.g. <code>3.1415926</code> or <code>-543</code>.<br />
<br />
A string: e.g. <code>'How now brown cow'</code> or <code>"How now brown cow"</code>.<br />
<br />
An arrray: e.g. <code>( 1, 1, 2, 3, 5, 8, 12 )</code>.<br />
<br />
A hash: e.g. <code>('ssn'=>'123-34-5676', 'name'=>'Jane Doe')</code>. The <code>=></code> symbol is translated into a comma, but using <code>=></code> implicity quotes the word to its left, meaning that <code>(ssn=>'123-34-5676', name=>'Jane Doe')</code> works too.<br />
<br />
=== Quotes ===<br />
<br />
Understanding how to create strings using quotes is important for writing WeBWorK PG problems. The two important concepts are interpolation of variables and temporarily redefining quote tokens.<br />
<br />
There are two basic types of quoted string constants. Double quoted strings "interpolate" variables embedded in the string {{--}} they replace variable names by the contents of the variable. Single quoted strings do not do this.<br />
<br />
Assuming that the value of $a_variable is 3 we have:<br />
<br />
:"Let a = $a_variable"</code> becomes <code>Let a = 3</code>.<br />
<br />
:'Let a = $a_variable'</code> remains <code>Let a = $a_variable</code>.<br />
<br />
A perpetual problem is how to insert a quote inside a quoted string. A standard method is to escape the quote. Remember that the escape character in PG is <code>~~</code>, ''not'' the backslash <code>\</code> as in normal Perl.<br />
<br />
'Don~~'t forget to escape single quotes within "single" quotes!'<br />
<br />
Perl has a more elegant method for handling this. You can temporarily redefine the quote character using the command <code>qq</code> for double quotes, or <code>q</code> for single quotes. Any character can be defined as a quote character.<br />
<br />
qq!Any character but the exclamation point can occur in this quoted string!<br />
q~The variable $A will not be interpolated in this single quoted string~<br />
qq{Parentheses, brackets and braces { must be balanced } when used as quote tokens.}<br />
<br />
More on interpolation and on quoting text blocks can be found in the section on the <code>BEGIN_TEXT...END_TEXT</code> construction.<br />
<br />
=== Functions ===<br />
<br />
The function names that are not followed by parentheses must have & in front. (The words function, subroutine and macro are used intechangeably in this document.)<br />
<br />
The function <code>beginproblem</code> requires no arguments (i.e. no parentheses after it), therefore we can write it as <code>&beginproblem</code> or as <code>beginproblem()</code> but not <code>beginproblem</code> which will usually cause a compiler warning message about "barewords" appearing in the problem.<br />
<br />
=== Mathematical operations ===<br />
<br />
The Perl symbol for taking some value to a power is <code>**</code>. To take variable <code>$a</code> to the power <code>2</code>, write <code>$a**2</code>, and not <code>$a^2</code>. (When using [[MathObjects]] to specify a formula as a string you can use either <code>**</code> or <code>^</code>. Students can use <code>^</code> as well.<br />
<br />
=== References {{--}} more complicated data types ===<br />
<br />
==== References ====<br />
<br />
To handle objects, which are more complicated structures than scalars, lists and hashes we use references. A '''reference''' is a scalar which is not the object itself, but the address of the object. For example <code>$ml = new_match_list()</code> can't really fit an entire matching list object into the scalar variable $ml, instead it just stores the address of where the object structure is stored. An '''object''' is a structure which contains both data and functions (called methods) which operate on that data. You can tell that <code>$ml</code> is a reference to an object and not just a number, because the statement <code>ref($ml)</code> will return <code>Match</code> (the type of a matching list object). In general <code>ref($var)</code> will print out the kind of object pointed to by a scalar variable, and will print nothing if it is just an ordinary number or string.<br />
<br />
==== Calling and object's methods ====<br />
<br />
<code>$ml->choose(4)</code> tells the match list object <code>$ml</code> to perform its <code>choose</code> method, choosing 4 arguments. The beauty of objects and methods over standard subroutines is that you don't have to give the choose subroutine a list of questions and answers to choose from {{--}} it already 'knows' what questions and answers it has available and will choose 4 of them. The arrow construction is the same as the period construction in Java. In Java you would write <code>ml.choose()</code>. Java's typography is much neater, but unfortunately the period was already being used for string concatenation by Perl, so we're stuck with the arrow construction, which takes up more space.<br />
<br />
==== Pointers to arrays and hashes ====<br />
<br />
You can use references to arrays and to hashes too if you want:<br />
<br />
:<code>ref($ra_foo)</code> prints <code>ARRAY</code> and is a reference to an array variable. You write $ra_foo->[1] to get the second item stored in the array.<br />
<br />
:<code>$ra_foo->[1]->[0]</code> can be shortened to <code>$ra_foo->[1][2]</code> to simplify addressing multidimensional arrays. You can also write <code>~~@array = ~~@{$ra_foo}</code> which has now stored the array pointed to by <code>$ra_foo</code> in the new array variable <code>~~@array</code>.<br />
<br />
:<code>ref($rh_foo)</code> prints <code>HASH</code> and is a reference to a hash variable. <code>$rh_foo->{first_name}</code> gets the value associated with the key 'first_name'. <code>%hash = %{$rh_foo}</code> stores the referenced hash in the new hash variable <code>%hash</code>.<br />
<br />
:<code>ref($rf_foo)</code> prints 'CODE' and is a reference to a function or subroutine. The construction <code>&{$rf_foo}(34)</code> takes the value <code>34</code> and uses it as an argument for the subroutine referenced by <code>$rf_foo</code>.<br />
<br />
Note that the array reference variable started with <code>$ra_</code>, the hash reference variable started with <code>$rh_</code> and the function reference variable started with <code>$rf_</code>. This is a naming convention PG uses, (which is voluntary, not enforced) which helps keep track of the kind of reference stored in a scalar variable. The convention is useful for macros, and is probably overkill for most short PG problems.<br />
<br />
== See also ==<br />
<br />
* [[MathObjects]]<br />
* [http://perldoc.perl.org/perlintro.html perlintro] {{--}} a brief introduction and overview of Perl<br />
* [http://perldoc.perl.org/perldsc.html perldsc] {{--}} Perl Data Structures Cookbook<br />
<br />
[[Category:Authors]]<br />
[[Category:Needs Work]]</div>Xiong Chiamiovhttps://webwork.maa.org/mediawiki_new/index.php?title=Installation_Manual_for_2.4_on_Ubuntu_8.04&diff=3268Installation Manual for 2.4 on Ubuntu 8.042008-07-03T20:15:52Z<p>Xiong Chiamiov: /* Install the National Problem Library */ added quantitative number of files so they know about how long it'll take</p>
<hr />
<div>These instructions cover the installation of the Ubuntu Linux 8.04 operating system and WeBWorK 2.4 from scratch. <br />
<br />
They 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.<br />
<br />
== Notation ==<br />
<br />
First some short comments on notation we will be using. We will use <code>&lt;key&gt;</code> to indicate that you should press a specific key (e.g. <code>&lt;Enter&gt;</code>, <code>&lt;Tab&gt;</code>, <code>&lt;F12&gt;</code>, etc.). Sometimes we will also use e.g. <code>&lt;root password&gt;</code> to indicate you have to enter the root password.<br />
<br />
<code>^</code> will indicate the <code>&lt;Ctrl&gt;</code> key so e.g. <code>^X</code> is really shorthand for <code>&lt;Ctrl&gt; &lt;X&gt;</code>, i.e. press the Ctrl key and hit the X key.<br />
<br />
We will give references to specific versions of software, e.g. httpd-2.2.4.tar.gz rather than the more general httpd-2.x.x.tar.gz. In most cases you should be able to use the latest stable version but we have only tested the versions listed.<br />
<br />
== Installing the Ubuntu 8.04 Linux Operating System ==<br />
<br />
===Installation CD ===<br />
Obtain the <code>Desktop Edition, Alternate</code> installation DVD/CD set. Connect to http://www.ubuntu.com/ for information. On the download page http://www.ubuntu.com/getubuntu/download make sure you check the box for <code>Check here if you need the alternate desktop CD. This CD does not include the Live CD, instead it uses a text-based installer</code>. For example you can use wxDownload Fast or BitTorrent to download an ISO image of the installation CD and then burn your own installation CD. 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/7.04/MD5SUMS). wxDownload Fast automatically calculates the MD5 checksums which is convenient. I have had good luck downloading from mirrors.kernel.org but your experience may differ. These instructions will assume you have the installation CD but installing from a commercial DVD/CD set or from the net should be essentially identical.<br />
<br />
Place the installation CD in your DVD/CD drive and reboot your computer from the DVD drive. You may have to press <code>&lt;F12&gt;</code> 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.<br />
<br />
First select <code>English</code> by just hitting <code>&lt;Enter&gt;</code>.<br />
<br />
You will see a list of options. <br />
<br />
# If you want hit <code>&lt;F1&gt;</code> to obtain help and see additional boot methods<br />
# You can just hit <code>&lt;Enter&gt;</code> to accept the default install method except in the following situation<br />
# If your network has DHCP enabled but you want to setup your server with a static IP address, then hit <code>&lt;F6&gt;</code> and on the <code>Boot OPtions</code> line move the cursor before <code>quiet --</code> and type <code>netcfg/disable_dhcp=true</code> , leave a space before <code>quiet</code> and then hit <code>&lt;Enter&gt;</code><br />
# A succession of pages follow, for each select the obvious option and hit <code>&lt;Enter&gt;</code>. For example my obvious options are <code>English</code>, <code>United States</code>, <code>&lt;No&gt;</code>, <code>USA</code> and <code>USA</code> <br />
# The system will than scan your CD and load various components<br />
# If your system has multiple network interfaces, you will be asked to select the one to be used during the installation (which will usually be a hard wired ethernet connection)<br />
# Unless you entered the <code>netcfg/disable_dhcp=true</code> boot option above, the system will try to configure your network using DHCP. If you have DHCP, your network interface will be set up automatically. If you don't have DHCP, automatic network configuration will fail quickly (or just hit <code>&lt;Enter&gt;</code> to <code>Cancel</code> if you are impatient). Then hit <code>&lt;Enter&gt;</code> to <code>Continue</code><br />
<br />
'''Manual network configuration'''. If your network interface was set up automatically by DHCP, you can skip the rest of this paragraph. Otherwise you will have to enter your machine's static ip address, etc. To do this<br />
# Select <code>Configure network manually</code><br />
# Enter your computer's IP address and use <code>&lt;Tab&gt;</code> to select <code>Continue</code><br />
# The <code>netask</code> is probably OK as it but another possibility may be 255.255.0.0<br />
# Enter the ip address of your gateway router. Ubuntu makes a good guess at this, but your network may be set up differently.<br />
# Next enter the ip address(es) of up to 3 nameservers separated by spaces (at a minimum you have to enter the ip address one nameserver)<br />
# Enter the name of your server<br />
# Enter the domain name for the domain your server sits on (e.g. math.myschool.edu)<br />
# This completes the static ip address setup<br />
<br />
Now select your time zone and wait for the clock to be configured<br />
<br />
===Optional Configurations===<br />
<br />
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.<br />
<br />
'''Optional A''' creates a separate partition 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 means that it is easier and faster to back up other partitions and skip backing up unnecessary files.<br />
<br />
'''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.<br />
<br />
'''Optional C''' configures Apache so that access to WeBWorK will be through an encrypted Secure Sockets Layer (SSL) with an https: URL.<br />
<br />
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.<br />
<br />
===Partition disks===<br />
Next comes the <code>Partition disks</code> 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. <br />
<br />
'''Optional A''': The default partitioning scheme creates just two partitions, a root (<code>/</code>) partition and a swap partition. Here we will create those and an additional partition for WeBWorK's temporary files.<br />
<br />
# On the <code>Partition disks</code> page use <code>&lt;Tab&gt;</code> to select <code>Go Back</code> and then select <code>Partition disks</code> <br />
# Use the down arrow to select your disk (<code>sda</code>)<br />
# On the <code>You have selected an entire device to partition...</code> page select <code>Yes</code> to the question <code>Create new empty partition table on this device</code><br />
# On the <code>This is an overview...</code> page select <code>FREE SPACE</code><br />
# On the <code>How to use this free space</code> page select <code>Create a new partition</code><br />
# 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 (<code>/</code>) partition. Actually if you are going through the trouble of doing this, you probably will want to research other partitioning recommendations.<br />
# On the <code>The maximum size you can use...</code> page enter the size for your root (<code>/</code>) partition and <code>Continue</code><br />
# Select <code>Primary</code> for the type of the new partition<br />
# Select <code>Beginning</code> for the location of the new partition<br />
# Select <code>/</code> for the Mount point of the new partition and then select <code>Done setting up the partition</code><br />
<br />
Now we repeat the process for the partition which will hold WeBWorK's temporary files.<br />
# On the <code>This is an overview...</code> page select <code>FREE SPACE</code><br />
# On the <code>How to use this free space</code> page select <code>Create a new partition</code><br />
# On the <code>The maximum size you can use...</code> page enter the size for WeBWorK's temporary files partition. As we said 25 GB for every 1,000 students should be ample. Then <code>Continue</code><br />
# Select <code>Logical</code> for the type of the new partition<br />
# Select <code>Beginning</code> for the location of the new partition<br />
# Select <code>Mount point</code> and then hit <code>&lt;Enter&gt;</code><br />
# Select <code>Enter manually</code> and then hit <code>&lt;Enter&gt;</code><br />
# For the <code>Mount point for this partition</code> enter <code>/var/www/wwtmp</code> and <code>Continue</code><br />
# Then select <code>Done setting up the partition</code><br />
<br />
Finally we set up the swap partition<br />
# On the <code>This is an overview...</code> page select <code>FREE SPACE</code><br />
# On the <code>How to use this free space</code> page select <code>Create a new partition</code><br />
# On the <code>The maximum size you can use...</code> 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 <code>Continue</code><br />
# Select <code>Logical</code> for the type of the new partition<br />
# Select <code>Beginning</code> for the location of the new partition<br />
# Select <code>Use as</code> and then hit <code>&lt;Enter&gt;</code><br />
# Select <code>swap area</code> and then hit <code>&lt;Enter&gt;</code><br />
# Then select <code>Done setting up the partition</code><br />
<br />
Finally <br />
# Review your changes and<br />
# Select <code>Finish partitioning and write changes to disk</code> and then hit <code>&lt;Enter&gt;</code><br />
# Select <code>Yes</code> to confirm the changes<br />
<br />
===Base Installation===<br />
# Now the base installation takes place --- this takes a short time<br />
# Enter yourself as a user (with user name and password). Note this account will function partially as the <code>root</code> account so you might want to pick a different username and password than you regularly use. <br />
# You can probably leave the HTTP proxy information blank<br />
# Now sit back and relax while a lot of software is installed --- this takes awhile<br />
<br />
The final step is to install the boot loader. I have a non standard setup and for some reason I had trouble installing the Grub boot loader but Lilo worked fine. Almost certainly, Grub will work fine for you<br />
<br />
===Continue Installation ===<br />
After this finishes the system will eject the CD and ask you to reboot. <br />
<br />
# Log into your account <br />
# Accept any available updates. You may see a little notification icon (it has a arrow on it) to the right of your name in the upper right hand corner of the screen --- click on it. Alternately you can select <code>System</code>, <code>Administration</code>, <code>Update Manager</code>. Click <code>install Updates</code>. You may have to enter the <code>&lt;your password&gt;</code> which functions as the <code>&lt;root password&gt;</code> . Follow any instructions, e.g. you may be told to reboot as soon as the installation is completed (to reboot, select <code>System</code>, <code>Quit</code> and then <code>Restart</code>)<br />
<br />
===Test Browser and Keyboard ===<br />
<br />
After reboot and login, click on <code>Applications</code>, <code>Internet</code>, <code>Firefox Web Browser</code> (or just click the Firefox icon at the top of the screen) and you should be connected to the world. <br />
Goto <br />
http://webwork.maa.org/wiki/Installation_Manual_for_2.4_on_Ubuntu_8.04<br />
where you can view this document and, if you want, copy commands that you need (see below).<br />
<br />
If something is wrong and you are not connected to the web, the first thing to do is check that you entered the correct network information.<br />
# Select <code>System</code>, <code>Administration</code>, <code>Network</code><br />
# Click on <code>Unlock</code><br />
# Enter <code>&lt;your password&gt;</code> and click <code>Authenticate</code><br />
# Select <code>Wired connection</code> and click <code>Properties</code><br />
# Check that all the entries are correct and edit them if they are not<br />
# Then click <code>OK</code><br />
# Next click on <code>DNS</code> and check the name server entries and correct if necessary<br />
# Click on <code>Close</code> to close <code>Network settings</code><br />
Your network connection should start up almost immediately. If you are still having problems it's time to investigate further or seek help.<br />
<br />
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. Click <code>System</code>, <code>Preferences</code>, <code>Keyboard</code> and then increase the delay time interval and hit <code>Close</code>.<br />
<br />
== Terminal Window Notation and Use ==<br />
<br />
Before installing and configuring additional software, we need to talk about terminal windows.<br />
<br />
To open a terminal window click <code>Applications</code>, <code>Accessories</code> and then select <code>Terminal</code>.<br />
<br />
In a terminal window some commands will have to be run as root whereas<br />
others should be run as a regular user. We will use # to indicate<br />
that the command is to be run as root e.g.<br />
<br />
# perl -MCPAN -e shell<br />
<br />
and $ to indicate that the command is to be run as a normal user e.g.<br />
<br />
$ cp .bashrc .bashrc.bak1<br />
<br />
To execute the above commands you have to hit <code>&lt;Enter&gt;</code>. We'll just assume this. <br />
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.<br />
<br />
The bash shell which you will be using has a number of very<br />
convenient features.<br />
<br />
One is command and file name completion. If you are typing (e.g.<br />
<code>ch</code>) and hit <code>&lt;tab&gt;</code> bash will complete the command or filename if it is<br />
unambiguous (or more precisely it will complete as much as possible).<br />
If there are multiple possibilities (as in the case of <code>ch</code>) nothing will<br />
happen (except you may hear a beep) and you can type more letter(s) and hit <code>&lt;tab&gt;</code> again. Or you can<br />
hit <code>&lt;tab&gt;</code> a second time and you will see a list of all possible<br />
completions. E.g. entering <code>ch&lt;tab&gt;&lt;tab&gt;</code> gives a list of possible<br />
completions and <code>ch&lt;tab&gt;g&lt;tab&gt;</code> (or <code>chg&lt;tab&gt;</code>) gives <code>chgrp</code>, the change group command. This<br />
is very fast and convenient and it also leads to fewer typing errors.<br />
<br />
Another useful shortcut is the command history. Using the up and down<br />
arrow keys will bring up previous commands which can be edited and then<br />
executed. If you are repeating a command or entering a command which<br />
is similar to a previous one, this is very useful.<br />
<br />
You can copy commands from these instructions (with <code>copy</code> from the Edit dropdown list or <code>^C</code>) and paste them into a terminal window<br />
(with <code>paste</code> from the Edit dropdown list or <code>&lt;Shift&gt; &lt;Ctrl&gt; &lt;V&gt;</code>). However typing yourself using command completion is probably just as fast except if a command is long.<br />
<br />
By default Ubuntu has no password set for the root user. To gain root access you have to type in your own user password. This is the password you set for the first user while installing Ubuntu. However we will<br />
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:<br />
<br />
$ sudo passwd<br />
Password: <your password><br />
<br />
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'''.<br />
<br />
Enter new UNIX password: <root password><br />
Retype new UNIX password: <root password><br />
passwd: Password updated successfully<br />
$<br />
<br />
To test this <br />
<br />
$ su<br />
Password: <root password><br />
# whoami<br />
root<br />
#exit<br />
$<br />
<br />
Finally perhaps a safer way to run commands as <code>root</code> is to use the <code>sudo</code> command<br />
<br />
$ sudo <command><br />
Password: <your password><br />
<br />
After you enter the password the command is executed. For a certain period (maybe 5 minutes) you can execute additional <code>sudo</code> commands without reentering <code>&lt;your password&gt;</code>. A log of all <code>sudo</code> commands is kept (I don't know where). In these instructions for the most part we will not use <code>sudo</code>, but keep it in mind for other times that you have to become <code>root</code> in order to execute a few commands (e.g. restarting <code>Apache</code>).<br />
<br />
Note that for certain GUI tools such as the <code>Synaptic Package Manager</code> that require root access, the password required is <code>&lt;your password&gt;</code>, the password for the first account you set up, not the new <code>&lt;root password&gt;</code>.<br />
<br />
For our next terminal window task create a <code>downloads</code> directory where we will keep copies of downloaded software.<br />
<br />
$ cd<br />
$ mkdir downloads<br />
<br />
==Ubuntu Software Packages ==<br />
<br />
Our next task is to install a number of Ubuntu software packages.<br />
<br />
# Select <code>System</code>, <code>Administration</code> and then <code>Synaptic Package Manager</code>. You will have to enter the <code>&lt;your password&gt;</code>. The <code>Synaptic Package Manager</code> window will open<br />
# Click on <code>Reload</code> to bring the package information up to date<br />
<br />
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 <code>libnet-ldap-perl</code> and then just give the list of required packages.<br />
<br />
# Select <code>Search</code> <br />
# Under <code>Look in:</code> select <code>Name</code>. The default <code>Description and Name</code> sometimes returns too many possibilities<br />
# We are searching for <code>libnet-ldap-perl</code> so enter <code>ldap-perl</code> (or something similar; you can copy and paste from this document if you want) and click on <code>Search</code><br />
# This should result in 3 possibilities. Select and Mark for Installation (by double clicking or checking and then selecting <code>Mark for Installation</code>) <code>libnet-ldap-perl</code>. You will see a pop up window <code>Mark additional required changes?</code> and you should always click <code>Mark</code> to accept the requirements.<br />
# Follow this basic procedure for all the packages listed below<br />
<br />
Here is the list of Debian packages that need to be installed. See [[Installation Manual for 2.4]] for a short explanation of what most of these packages do. <br />
<br />
# <code>apache2</code><br />
# <code>apache2-mpm-prefork</code><br />
# <code>cvs</code><br />
# <code>dvipng</code><br />
# <code>libapache2-request-perl</code><br />
# <code>libdatetime-perl</code><br />
# <code>libdbd-mysql-perl</code><br />
# <code>libemail-address-perl</code><br />
# <code>libextutils-xsbuilder-perl</code><br />
# <code>libgd-gd2-perl</code><br />
# <code>libmail-sender-perl</code><br />
# <code>libnet-ldap-perl</code><br />
# <code>libossp-uuid-perl</code><br />
# <code>libsql-abstract-perl</code><br />
# <code>libstring-shellquote-perl</code><br />
# <code>libtimedate-perl</code><br />
# <code>libxml-parser-perl</code><br />
# <code>libxml-writer-perl</code><br />
# <code>mysql-server-5.0</code><br />
# <code>netpbm</code><br />
# <code>openssh-server</code><br />
# <code>preview-latex-style</code><br />
# <code>tetex-bin</code><br />
# <code>tetex-extra</code><br />
<br />
When I do this I see on the bottom of <code>Synaptic Package Manager</code> window <code>82 to install/upgrade</code>, <code>1 to remove</code>. Your numbers may differ slightly. <br />
Now click <code>Apply</code> and <code>Apply</code> again to confirm the changes. You will be asked several times to enter a<br />
<code>New password for the MySQL "root" user</code>; just hit <code>&lt;Enter&gt;</code> which gives the default blank password. We will fix this and several other MySQL security issues below.<br />
<br />
That completes the set up of your base Ubuntu system. You can quit the <code>Synaptic Package Manager</code>.<br />
<br />
<br />
If you would prefer to install all of these packages in one fell swoop, run this command as root:<br />
<br />
<code># aptitude install apache2 apache2-mpm-prefork cvs dvipng libapache2-request-perl libdatetime-perl libdbd-mysql-perl libemail-address-perl libextutils-xsbuilder-perl libgd-gd2-perl libnet-ldap-perl libossp-uuid-perl libsql-abstract-perl libnet-ldap-perl libsql-abstract-perl libstring-shellquote-perl libtimedate-perl libxml-parser-perl libxml-writer-perl mysql-server-5.0 netpbm openssh-server preview-latex-style tetex-bin tetex-extra</code><br />
<br />
== Installing Perl Modules ==<br />
We now have to install several additional Perl modules which unfortunately are not available from the Debian package system.<br />
<br />
=== Testing Perl Modules ===<br />
To test if a Perl module is installed and working on your system, issue the following command, replacing <code>Module</code> with the name of the module:<br />
<br />
$ perl -MModule -e 'print "installed!\n"'<br />
<br />
If the module is installed you will see <code>installed!</code>. If not you will see at lot of gibberish. E.g. at this stage in our installation process <code>CPAN</code> is installed and <code>MXML::Parser::EasyTree</code> is not so<br />
<br />
$ perl -MCPAN -e 'print "installed!\n"'<br />
<br />
yields<br />
<br />
installed!<br />
<br />
and<br />
<br />
$ perl -MXML::Parser::EasyTree -e 'print "installed!\n"'<br />
<br />
yields<br />
<br />
Can't locate XML/Parser/EasyTree.pm in @INC (@INC contains: <br />
/etc/perl /usr/local/lib/perl/5.8.8 /usr/local/share/perl/5.8.8<br />
...<br />
<br />
=== Installing Additional Perl Modules from CPAN ===<br />
<br />
Be aware that in rare cases you might have to <br />
as root run<br />
<br />
$ su<br />
<root password><br />
# unset LANG<br />
# exit<br />
$<br />
<br />
since otherwise the installation of some modules (Module::Build is an example) may fail.<br />
<br />
First we will set up CPAN. For this you have to be root.<br />
<br />
$ su<br />
<root password><br />
# perl -MCPAN -e shell<br />
<br />
Since this is the first time you are using CPAN it will ask you <code>Are you ready for manual configuration?</code> <br />
Respond <code>no</code> and that should be it. <br />
<br />
Next we add at least one mirror and reload the index. A list of mirrors can be found at http://mirrors.cpan.org. To add the mirror ftp://mirrors.kernel.org/pub/CPAN and reload the index do the following. For me, a slow and inaccurate typist, copying (<code>^C</code>) and pasting (<code>&lt;Shift&gt; &lt;Ctrl&gt; &lt;V&gt;</code>) is much faster.<br />
<br />
cpan> o conf urllist push ftp://mirrors.kernel.org/pub/CPAN<br />
cpan> reload index<br />
<br />
Note that one time this failed when I tried to do it in the evening but when I tried again the next morning it worked fine. Now we update CPAN itself<br />
<br />
cpan> install Bundle::CPAN<br />
<br />
and always hit <code>&lt;Enter&gt;</code> to accept the defaults when prompted. This can be a long process with many long pauses. Please be patient. <br />
When you again see the <br />
<br />
cpan><br />
<br />
prompt enter<br />
<br />
cpan> reload cpan<br />
cpan> o conf commit<br />
<br />
Now install the following modules<br />
<br />
cpan> install XML::Parser::EasyTree Iterator Iterator::Util Net::IP <br />
<br />
and in case you are prompted accept all defaults by just hitting <code>&lt;Enter&gt;</code>. <br />
Note that with more than one module to install, we just list them after <code>install</code> separated by spaces.<br />
<br />
When you again see the <br />
<br />
cpan><br />
<br />
prompt enter<br />
<br />
cpan> exit<br />
#<br />
<br />
=== Installing Additional Perl Modules from Source ===<br />
At one point in time (August 2006), the installation of <code>DateTime</code> using CPAN was broken. Currently <code>DateTime</code> 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. <br />
<br />
'''IMPORTANT:''' With Debian we have already installed <code>DateTime</code> 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.<br />
<br />
Now we give the example of installing <code>DateTime</code> from source. As we said you can skip this part.<br />
<br />
Goto http://search.cpan.org/,<br />
search for <code>DateTime</code> and click on <code>DateTime</code>. Then near the top right download <code>DateTime-0.36.tar.gz</code> and save it to disk. Move it to your <code>downloads</code> directory. Then<br />
<br />
$ cd <br />
$ cd downloads<br />
$ tar -zvxf DateTime-0.36.tar.gz<br />
$ cd DateTime-0.36/<br />
<br />
<br />
$ perl Makefile.PL<br />
$ make<br />
$ make test<br />
<br />
If <code>make test</code> indicates something is missing you will have to install that. In fact in the case of <code>DateTime</code>, you would see that quite a few things are missing.<br />
<code>DateTime</code> requires the additional modules <code>version</code> , <code>Module::Build</code> , <code>Class::Singleton</code> , <code>DateTime::TimeZone</code> and <code>DateTime::Locale</code> . We could install these using CPAN<br />
<br />
# perl -MCPAN -e shell<br />
cpan> install version Module::Build Class::Singleton DateTime::TimeZone DateTime::Locale<br />
cpan> exit<br />
# exit<br />
$<br />
<br />
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<br />
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 <code>package/file.pm</code> was not found, you should serach for and install <code>package::file</code> since perl modules use a double colon (<code>::</code>) as a directory separator.<br />
<br />
Assuming all is OK<br />
<br />
$su<br />
<root password><br />
# make install<br />
# exit<br />
$<br />
<br />
Finally you should definitely test that the module (e.g. <code>DateTime</code>) was installed sucessfully<br />
<br />
$ perl -MDateTime -e 'print "installed!\n"'<br />
<br />
If you see <br />
<br />
installed!<br />
<br />
you can celebrate.<br />
<br />
== Apache 2 and mod_perl ==<br />
<br />
First we have to enable a couple Apache modules. Acting as <code>root</code> in a terminal window enter<br />
<br />
# a2enmod apreq<br />
# a2enmod info<br />
<br />
Next we make a copy of the configuration files for safekeeping. <br />
<br />
# cd /etc/apache2/mods-available<br />
# cp info.conf info.conf.bak1<br />
# cp status.conf status.conf.bak1<br />
<br />
Now we will edit configuration files <code>info.conf</code> and <code>status.conf</code> to allow us to view information about the setup and performance of the web server. Note that this is not absolutely necessary but it can be very useful. You can use your favorite editor but we will give instructions assuming you are using <code>gedit</code>. Note that you have to be root to edit these files. First we edit <code>info.conf</code><br />
<br />
# cd /etc/apache2/mods-available<br />
# gedit info.conf<br />
<br />
I suggest you allow access to server information from e.g. your department domain. To do this uncomment (i.e. remove the <code>#</code> from) <br />
# Allow from .example.com<br />
and then replace <code>.example.com</code> by <code>.math.yourschool.edu</code><br />
where of course you should edit <code>.math.yourschool.edu</code> appropriately. <br />
<br />
Then save the file and quit (<code>Save</code> and <code>File</code>, <code>Quit</code>).<br />
<br />
Now we edit <code>status.conf</code><br />
<br />
# cd /etc/apache2/mods-available<br />
# gedit status.conf<br />
<br />
After the comments at the top and above the <code><Location /server-status></code> line enter<br />
<br />
ExtendedStatus On<br />
<br />
Now edit the <br />
# Allow from .example.com<br />
line just as you did for <code>info.conf</code>.<br />
Then save the file and quit<br />
<br />
Now we have to set your server's fully qualified domain name. <br />
# Select <code>System</code>, <code>Administration</code>, <code>Network</code><br />
# Click on <code>Unlock</code><br />
# Enter <code>&lt;your password&gt;</code> and click <code>Authenticate</code><br />
# Click on <code>General</code><br />
# Under <code>Host name</code> enter <code>your_server_name</code> (if it's not already there)<br />
# Then under <code>Domain name</code> enter your server's domain name, something like <code>department.school.edu</code><br />
<br />
Next<br />
# Click on <code>Hosts</code><br />
#There should also be an entry with your server's IP address (if not you should add one)<br />
# Select the entry with your server's IP address and click <code>Properties</code><br />
# Under Aliases you should see your server's fully qualified domain name, something like <code>your_server_name.department.school.edu</code><br />
# Add or edit these entries if they are not correct<br />
# Then click <code>OK</code><br />
# And click <code>Close</code> to close <code>Network settings</code><br />
<br />
You can check these settings by running the commands<br />
<br />
$ hostname --fqdn<br />
<br />
and <br />
<br />
$ hostname<br />
<br />
The first respond with the fully qualified domain name and the second with just <code>your_server_name</code>.<br />
<br />
If the command <code>hostname --fqdn</code> returns <code>Unknown host</code> do the following:<br />
<br />
# Select <code>System</code>, <code>Administration</code>, <code>Network</code><br />
# Click on <code>Unlock</code><br />
# Enter <code>&lt;your password&gt;</code> and click <code>Authenticate</code><br />
# Click on <code>Hosts</code><br />
# Select the entry with your server's IP address and click <code>Properties</code><br />
# Under Aliases you should see your server's fully qualified domain name, something like <code>your_server_name.department.school.edu</code><br />
# Select the entry <code>127.0.0.1</code> and click <code>Properties</code><br />
# Under Aliases make sure you have the following entries in order<br />
## first your server's fully qualified domain name, something like <code>your_server_name.department.school.edu</code><br />
## second your server's name, something like <code>your_server_name</code><br />
## third <code>localhost</code><br />
# Click <code>Add</code> and add an entry with <code>IP address</code> <code>127.0.1.1</code> and under <code>Aliases</code> put your server's fully qualified domain name, something like <code>your_server_name.department.school.edu</code><br />
# Then click <code>OK</code><br />
# And click <code>Close</code> to close <code>Network settings</code><br />
<br />
Then check again by running the commands<br />
<br />
$ hostname --fqdn<br />
<br />
and <br />
<br />
$ hostname<br />
<br />
Note that if your server can not find its fully qualified domain name, certain tools (such as the Synaptic Package Manager) will not start.<br />
<br />
Now restart Apache<br />
<br />
$su<br />
<root password><br />
# apache2ctl graceful<br />
# exit<br />
$<br />
<br />
and test your server by connecting to<br />
"http://localhost/" and/or connecting to your<br />
server from a browser on a remote machine. You should see the page '''It works!''' indicating that Apache is running.<br />
<br />
You can check Apache's status by connecting to<br />
"http://localhost/server-status" using a browser on your machine or from a browser on a remote machine in the math.yourschool.edu domain.<br />
<br />
Further test Apache by connecting to<br />
"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 <br />
information about Apache. In particular under <code>Server Settings</code> you should see<br />
<br />
Server Version: Apache/2.2.8 (Ubuntu) mod_apreq2-20051231/2.6.0 mod_perl/2.0.3 Perl/v5.8.8<br />
<br />
indicating that both <code>mod_apreq2</code> and <code>mod_perl</code> are installed.<br />
<br />
If you have problems now or in the future, a good first thing to do is to look at the Apache error log which is located at <code>/var/log/apache2/error.log</code>. In the directory <code>/var/log/apache2/</code> you can "less" through the error log (<code>less error.log</code>), look at the last few entires (<code>tail error.log</code>) or run the command <code>tail -f error.log</code> which will display new error messages as they are appended to the file. Use <br />
<code>^C</code> to break out of <code>tail -f</code> .<br />
<br />
== Checking MySQL ==<br />
<br />
First check that MySQL is running by <br />
<br />
$ mysql -u root<br />
<br />
You should see<br />
<br />
Welcome to the MySQL monitor. Commands end with ; or \g.<br />
Your MySQL connection id is 1<br />
Server version: 5.0.51a-3ubuntu5 (Ubuntu)<br />
<br />
Type 'help;' or '\h' for help. Type '\c' to clear the buffer.<br />
<br />
mysql> <br />
<br />
Enter <code>exit</code> to exit<br />
<br />
mysql> exit<br />
Bye<br />
$<br />
<br />
== Reboot and Test ==<br />
<br />
Now reboot the system (<code>System</code>, <code>Quit</code>, <code>Restart</code>).<br />
<br />
Now connect to<br />
"http://localhost/" using a browser on your machine and/or to your<br />
server from a browser on a remote machine. You should see the page '''It Works''' indicating that Apache is running.<br />
<br />
This is also a good time to check that 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 <code>Keyboard Interactive</code> to the list of "Authentication methods" under "Authentication" if it's not already there. <br />
<br />
Finally test that MySQL is running.<br />
<br />
$ mysql -u root<br />
...<br />
mysql> <br />
mysql> exit<br />
Bye<br />
$<br />
<br />
Currently the MySQL password is empty so we didn't need a password.<br />
We will take care of that now.<br />
<br />
== MySQL Security Issuses ==<br />
As initially set up, MySQL is a very open system. There are anonymous accounts with full privileges for some databases and the root accounts are not password protected. See e.g. http://dev.mysql.com/doc/refman/5.0/en/default-privileges.html for information on this. We recommend removing the anonymous accounts and giving passwords to the root accounts. There are three root accounts, one is <code>root@localhost</code>, one is <code>root@127.0.0.1</code> and the third is <code>root@host_name</code> where <code>host_name</code> is the name of your server. To find this name, do the following <br />
<br />
$ mysql -u root<br />
mysql> SELECT Host, User, Password FROM mysql.user;<br />
<br />
You will see a table with six entries. For <code>localhost</code> you will see three Users, <code>root</code> and <code>debian-sys-maint</code> and one with an empty name (the anonymous user). The other listed Host (with a <code>root</code> user and also one with an empty name) is the name of your server which we will denote by <code>host_name</code>. <br />
<br />
First we will remove the anonymous accounts. <br />
<br />
mysql> DELETE FROM mysql.user WHERE User = <nowiki>''</nowiki>;<br />
mysql> FLUSH PRIVILEGES;<br />
<br />
Now using the up arrow key repeat the command<br />
<br />
mysql> SELECT Host, User, Password FROM mysql.user;<br />
<br />
and you should get a table with only four users (three <code>root</code> and one <code>debian-sys-maint</code>). <br />
<br />
Now we will assign a password to these <code>root</code> accounts. <br />
<br />
In the third command below, replace <code>host_name</code> with the name of the server host. In all commands replace <code>newpwd</code> with your choosen MySQL <code>root</code> password. As was said above, '''Do not forget what you enter here'''. Also remember that this is the password for the MySQL <code>root</code> user, not the Ubuntu linux system <code>root</code> user. Below we refer to this as <code>&lt;mysql root password&gt;</code><br />
<br />
mysql> UPDATE mysql.user SET password=PASSWORD('newpwd') WHERE host='localhost' and user='root';<br />
mysql> UPDATE mysql.user SET password=PASSWORD('newpwd') WHERE host='127.0.0.1' and user='root';<br />
mysql> UPDATE mysql.user SET password=PASSWORD('newpwd') WHERE host='host_name' and user='root';<br />
mysql> FLUSH PRIVILEGES;<br />
<br />
Now use your up arrow key to run the command<br />
<br />
mysql> SELECT Host, User, Password FROM mysql.user;<br />
<br />
and you should see that all three users now have passwords (which will be displayed in encrypted form).<br />
<br />
Then exit MySQL<br />
<br />
mysql> exit<br />
Bye<br />
$<br />
<br />
<br />
and test that all is well:<br />
<br />
$ sudo /etc/init.d/mysql restart<br />
password:<your password><br />
$ mysql -u root -p <br />
Enter Password: <mysql root password><br />
<br />
You should see<br />
<br />
Welcome to the MySQL monitor ...<br />
mysql><br />
<br />
Enter<br />
<br />
mysql> SELECT Host, User, Password FROM mysql.user;<br />
<br />
and you should see encrypted passwords for all three accounts. Note that the way MySQL is set up, you can only gain access to the <code>localhost</code> account, not to the <code>host_name</code> account but setting a password for the <code>host_name</code> account is a safer thing to do in case the set up gets changed. Now exit MySQL<br />
<br />
mysql> exit<br />
Bye<br />
$ <br />
<br />
and congratulate yourself. You are now ready for the next and hopefully easy part, installing WeBWorK.<br />
<br />
== Downloading the WeBWorK System Software and Problem Libraries ==<br />
We are finally at the point where we can start downloading and installing WeBWorK. We will use CVS to download WeBWorK. This is easy and it will also make it easy to update the system in the future. Note that the following are rather long commands; it is much easier to copy (<code>^C</code>) them from this document and paste (<code>&lt;Shift&gt; &lt;Ctrl&gt; &lt;V&gt;</code>) them in a terminal window<br />
<br />
$ cd<br />
$ cd downloads<br />
<br />
$ cvs -d :pserver:anoncvs@cvs.webwork.rochester.edu:/webwork/cvs/system checkout -r rel-2-4-dev webwork2 pg<br />
$ cvs -d :pserver:anoncvs@cvs.webwork.rochester.edu:/webwork/cvs/asu checkout database_problems<br />
<br />
The first download gives you the latest released version with patches (don't be misled by the <code>dev</code> extension --- this is not a development version).<br />
The second download contains the WeBWorK National Problem Library. This now includes the Rochester and Union Libraries along with others as sunlibraries. There is quite a bit of overlap between these libraries but now you system is loaded with many thousands of WeBWorK problems (over 13,000 in the National Problem Library main collection alone).<br />
<br />
== Installing WeBWorK ==<br />
=== Move the System into the Required Directories ===<br />
As <code>root</code> create a <code>webwork</code> directory under <code>/opt</code> and move directories there. <br />
<br />
$ su<br />
<root password><br />
# mkdir /opt/webwork<br />
# mv webwork2 /opt/webwork/<br />
# mv pg /opt/webwork/<br />
<br />
Now create the <code>courses</code> and <code>libraries</code> directories under <code>webwork</code> and copy and move content there.<br />
<br />
# mkdir /opt/webwork/courses<br />
# mkdir /opt/webwork/libraries<br />
# mv database_problems/ /opt/webwork/libraries/<br />
# cd /opt/webwork/webwork2/courses.dist<br />
# cp *.lst /opt/webwork/courses/<br />
# cp -r modelCourse/ /opt/webwork/courses/<br />
<br />
=== Setting Permissions ===<br />
<br />
The PG installation directory and files should be owned by root and not writable by other users:<br />
<br />
# cd /opt/webwork/pg<br />
# chown -R root:root .<br />
# chmod -R u+rwX,go+rX .<br />
<br />
Most WeBWorK directories and files should also be owned by root and not writable by other users:<br />
<br />
# cd /opt/webwork/webwork2<br />
# chown -R root:root .<br />
# chmod -R u+rwX,go+rX .<br />
<br />
Certain data directories need to be writable by the web server. These are <code>DATA</code>, <code>courses</code>, <code>htdocs/tmp</code>, <code>logs</code>, and <code>tmp</code>. It is convenient to give WeBWorK administrators access to these directories as well, so they can perform administrative tasks such as removing temporary files, creating and editing courses from the command line, managing logs, and so on. We will create a new group called <code>wwdata</code>, containing both the WeBWorK administrators and the web server.<br />
<br />
# Select <code>System</code>, <code>Administration</code> and then <code>Users and Groups</code><br />
# Click on <code>Unlock</code><br />
# Enter <code>&lt;your password&gt;</code> and click <code>Authenticate</code><br />
# Select <code>Manage Groups</code><br />
# Click <code>Add Group</code> <br />
# For <code>Group name</code> enter <code>wwdata</code><br />
# Under <code>Group Members</code> select yourself and click <code>OK</code><br />
# Click <code>Close</code><br />
<br />
If there are other users who will also be administering WeBWorK files,<br />
now is a good time to add them. And remember to add them to the <code>wwdata</code> group as above.<br />
<br />
Because system users are not shown by default, we can not simply use the <code>Group Manager</code> to add the Apache2 webserver (which runs as <code>www-data</code>) to the <code>wwdata</code><br />
group so we will do this by hand.<br />
<br />
# cd /etc<br />
# cp group group.bak1<br />
# gedit group<br />
<br />
<br />
# In the gedit window scroll to the last line. <br />
# It should look like <code>wwdata:x:1001:<your userid></code><br />
# Append to this line <code>,www-data</code><br />
# Then Save and Quit<br />
<br />
<br />
<br />
You can check that this succeeded in a terminal window by entering<br />
<br />
# exit<br />
$ id <your userid><br />
<br />
and then you should see <code>wwdata</code> listed under groups. Also<br />
<br />
$ id www-data<br />
<br />
should show wwdata listed under groups. Now we make the WeBWorK directories that need to be writable by the web server have <code>wwdata</code> as their group. The following are rather long commands; you might want to copy them and paste them into your terminal window rather than typing them.<br />
<br />
$ su<br />
<root password><br />
# cd /opt/webwork/webwork2/<br />
# chgrp -R wwdata DATA ../courses htdocs/tmp logs tmp<br />
# chmod -R g+w DATA ../courses htdocs/tmp logs tmp<br />
# find DATA/ ../courses/ htdocs/tmp logs/ tmp/ -type d -a ! -name CVS -exec chmod g+s {} \;<br />
# exit<br />
$<br />
<br />
== Configuring the Shell ==<br />
<br />
To make working with WeBWorK easier, there are a couple of changes you can make to your shell environment.<br />
<br />
Add the WeBWorK <code>bin</code> directory to your path. This will allow you to run WeBWorK command-line utilities without typing the full path to the utility. Goto your home directory and backup your <code>.bashrc</code> file<br />
<br />
$ cd<br />
$ cp .bashrc .bashrc.bak1<br />
<br />
Now edit <code>.bashrc</code><br />
<br />
$ gedit .bashrc<br />
<br />
After the last line add the two lines:<br />
<br />
export PATH=$PATH:/opt/webwork/webwork2/bin<br />
export WEBWORK_ROOT=/opt/webwork/webwork2<br />
<br />
Then save the file and Quit.<br />
<br />
Close your Terminal Window and open a new one so the above changes<br />
take effect. You can check that they have by<br />
<br />
$ echo $PATH<br />
$ echo $WEBWORK_ROOT<br />
<br />
== Checking Module Dependancies ==<br />
<br />
<br />
<br />
WeBWorK includes a script called <code>check_modules.pl</code> that verifies that the needed programs and Perl modules are installed on your system. Run this script to make sure you have installed the required programs and Perl modules.<br />
<br />
$ check_modules.pl apache2<br />
<br />
Scroll up and look through the listing. It should find everything except <code>PHP::Serialization</code>, <code>SOAP::Lite</code>, <code>MIME::Parser</code> and <code>XMLRPC::Lite</code> which are only required if you plan to use WeBWorK with Moodle and <code>tth</code> which is a deprecated display mode. If something is missing (flagged by <code>**</code>), look back through these instructions and/or look at 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.<br />
<br />
== Configuring WeBWorK ==<br />
<br />
=== Making Copies of the Distribution Configuration Files ===<br />
<br />
Before configuring the system, you must make local copies of the <code>global.conf</code> and <code>database.conf</code> configuration files, located in <code>/opt/webwork/webwork2/conf/</code> . Since these are owned by <code>root</code><br />
<br />
$ su<br />
<root password><br />
# cd /opt/webwork/webwork2/conf<br />
# cp global.conf.dist global.conf<br />
# cp database.conf.dist database.conf<br />
<br />
=== Global Configuration ===<br />
<br />
Most WeBWorK configuration is done in the file <code>/opt/webwork2/conf/global.conf</code>. This file provides system-wide configuration settings, and defaults for course settings. Any setting in this file can be overridden in the <code>course.conf</code> file for a particular course. To override a setting for a course, just put the new setting (using the same syntax as is in <code>global.conf</code>) in the <code>course.conf</code> file.<br />
<br />
There are several options that must be set for WeBWorK to work with your system. The rest of the file consists of customization options. Now edit <code>global.conf</code><br />
<br />
# cd /opt/webwork/webwork2/conf<br />
# gedit global.conf<br />
<br />
WeBWorK uses the DateTime module. DateTime is supposed to be able to determine the local timezone itself without you having to enter it but this often fails so it is best to just set it here. For is a list of timezones recognized by DateTime go to<br />
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 <code>DateTime::TimeZone::America::New_York</code> and you should replace <code>$siteDefaults{timezone} = "";</code> by <code>$siteDefaults{timezone} = "America/New_York";</code> <br />
<br />
# Search for <code>$siteDefaults{timezone} = "";</code> and enter your local timezone.<br />
<br />
At this point <code>TtH</code> is a deprecated display mode which we didn't install so we have to remove it from the listof possible display modes. <br />
<br />
# Search for <code>formattedText</code> and comment out the line <code>"formattedText", # format math expressions using TtH</code><br />
so it becomes<br />
<br />
# "formattedText", # format math expressions using TtH<br />
<br />
We need to set a password that WeBWorK uses when it communicates with the MySQL database. Note that this is not the same as the <code>&lt;mysql root password&gt;</code> which is the password the MySQL root user uses.<br />
# Search for <code>$database_password = "";</code> and replace this by <br /> <code>$database_password = "database_password";</code> <br />
where of course you should replace 'database_password' with your own password. Remember this password as we will need it below.<br />
<br />
WeBWorK sends mail in three instances. The PG system sends mail to report answers to questionnaires and free-response problems. The mail merge module is used to send mail to course participants, i.e. to report scores. The feedback module allows participants to send mail to course instructors.<br />
<br />
To send mail, WeBWorK needs the address of an SMTP server. Normally you will use the address of your school's SMTP server. If the local machine is running an SMTP server, use <code>localhost</code>. IMPORTANT: Our instructions above did not install an SMTP server so you will have to install and configue one if you do not use your school's SMTP server. When connecting to the SMTP server, WeBWorK must also send an email address representing the sender of the email (this has nothing to do with the <code>From</code> address on the mail message). Edit the lines<br />
$mail{smtpServer} = 'mail.yourschool.edu'; <br />
$mail{smtpSender} = 'webwork@yourserver.yourschool.edu';<br />
<br />
entering the appropriate information.<br />
<br />
If you want WeBWorK questionnaires or similar things from different courses to be mailed to a central person or persons (e.g. the WeBWorK administrator), edit the lines<br />
<br />
$mail{allowedRecipients} = [<br />
#'prof1@yourserver.yourdomain.edu',<br />
#'prof2@yourserver.yourdomain.edu',<br />
];<br />
<br />
appropriately removing the <code>#</code> and using the professor(s) actual email address(es). In order to have professors from individual courses receive such email, this <br />
should be set in course.conf to the addresses of professors of each course.<br />
<br />
Then save the file and Quit.<br />
<br />
<br />
Now become a regular user again<br />
<br />
# exit<br />
$<br />
<br />
WeBWorK uses a single database, called <code>webwork</code>, for all courses. We will create the <code>webwork</code> database now.<br />
<br />
To do this do the following (before you just copy, paste and hit <code>&lt;Enter&gt;</code> notice that you have to replace <code>database_password</code> with the password you set when editing <code>global.conf</code> above):<br />
<br />
$ mysql -u root -p mysql<br />
Enter password: <mysql root password><br />
mysql> CREATE DATABASE webwork;<br />
mysql> GRANT SELECT, INSERT, UPDATE, DELETE, CREATE, ALTER, DROP, LOCK TABLES ON webwork.* TO webworkWrite@localhost IDENTIFIED BY 'database_password';<br />
mysql> exit<br />
Bye<br />
$ <br />
<br />
where as we said replace <code>database_password</code> with the password you set when editing <code>global.conf</code> above.<br />
<br />
Since version 2.3.0 WeBWorK has an automatic database upgrade system. Rather than manually issuing SQL commands to make changes to the database, or using ad-hoc scripts like wwdb_addgw, there is a single script called <code>wwdb_upgrade</code> that applies any necessary updates. It should be run when creating a new database, and any time you upgrade WeBWorK.<br />
<br />
$ /opt/webwork/webwork2/bin/wwdb_upgrade -v<br />
<br />
=== jsMath Settings ===<br />
<br />
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 <code>webwork2/htdocs/jsMath/jsMath-fonts.tar.gz</code>, and you need to unpack this tarball before jsMath will work properly. Use the command<br />
<br />
$ su<br />
<root password><br />
# cd /opt/webwork/webwork2/htdocs/jsMath<br />
# tar vfxz jsMath-fonts.tar.gz<br />
<br />
This will unpack the archive. Since there are 20,000 tiny files, it can take a little while, so the <code>v</code> 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.<br />
<br />
<br />
== Configuring Apache ==<br />
WeBWorK ships with an Apache config file that needs to linked into your Apache configuration process. The file is named <code>webwork.apache2-config.dist</code> and located in the <code>conf</code> directory. First, copy the file to <code>webwork.apache2-config</code>:<br />
<br />
# cd /opt/webwork/webwork2/conf<br />
# cp webwork.apache2-config.dist webwork.apache2-config<br />
<br />
and now link it into your Apache configuration process<br />
<br />
# cd /etc/apache2/conf.d<br />
# ln -s /opt/webwork/webwork2/conf/webwork.apache2-config webwork.conf<br />
<br />
Then restart Apache <br />
<br />
# apache2ctl graceful<br />
# exit<br />
$<br />
<br />
== Test your configuration ==<br />
<br />
# Test the <code>/webwork2</code> location by visiting <code>http://yourserver.yourschool.edu/webwork2</code>. You should see the WeBWorK home page with no courses listed. Actually the directory <code>/opt/webwork/courses/</code> does contain the <code>modelCourse</code> but the <code>modelCourse</code> is not a real course so you will get an error message if you try to log into it. It will be used a as model for setting up other courses. For this reason <code>/opt/webwork/courses/modelCourse/</code> contains a file named <code>hide_directory</code> and so the <code>modelCourse</code> is not visible.<br />
# Test the <code>/webwork2_files</code> location by visiting <code>http://yourserver.yourschool.edu/webwork2_files</code>. You should see the "WeBWorK Placeholder Page".<br />
# You cannot test the <code>/webwork2_course_files</code> location until you have created a course.<br />
<br />
==If Something is Wrong ==<br />
If something is wrong one of the first things to check is that the config files have been edited correctly (e.g. one time a wrapped line in <code>global.conf</code> caused me problems, another time it was a missing single quote). A quick way to check this is to do a <code>diff</code> between the edited and distributed versions and check that <code>diff</code> reports the changes you made and only those.<br />
<br />
# exit<br />
$<br />
$ cd /etc/apache2/<br />
$ diff apache2.conf apache2.conf.bak1<br />
$ cd /opt/webwork/webwork2/conf/<br />
$ diff global.conf global.conf.dist<br />
$ diff database.conf database.conf.dist<br />
$ diff webwork.apache2-config webwork.apache2-config.dist <br />
<br />
If something is wrong and you fix it, you will have to restart Apache for the changes to take effect<br />
<br />
$ su<br />
<root password><br />
# apache2ctl graceful<br />
# exit<br />
$<br />
<br />
== Create the admin Course ==<br />
<br />
[[Course Administration]] gives information about creating courses. Here we will give explicit instructions for doing this.<br />
<br />
$ su<br />
<root password><br />
# newgrp wwdata<br />
# umask 2<br />
# cd /opt/webwork/courses<br />
# /opt/webwork/webwork2/bin/addcourse admin --db-layout=sql_single --users=adminClasslist.lst --professors=admin<br />
# exit<br />
# exit<br />
$<br />
<br />
Now goto <code>http://yourserver.yourschool.edu/webwork2</code> and should see the WeBWorK home page with <code>Course Adninistration</code> listed at the top. Click on it and login with Username <code>admin</code> and Password <code>admin</code> . This first thing you should do is to click on <code>Password/Email</code> and change <code>admin</code> 's password to something more secure than <code>admin</code> . <br />
<br />
Unless you choose oherwise, users with <code>professor</code> privilges in the <code>admin</code> course (i.e. WeBWorK administrators) will automatically be added to new courses with <code>professor</code> privilges and the same password as in the <code>admin</code> course. Initially the only such user is <code>admin</code> (hopefully you are not confused by the fact that the course <code>admin</code> has a user named <code>admin</code>). It's usually convenient make yourself a WeBWorK administrator. To do this (assuming you are logged in as <code>admin</code> to the <code>admin</code> course at <code>http://yourserver.yourschool.edu/webwork2/admin</code> )<br />
# Click on <code>Classlist Editor</code> in the left panel<br />
# Check <code>Add 1 student(s)</code> and click <code>Take Action!</code><br />
# Enter the appropiate information (you can leave the last three items blank) and click <code>Add Students</code><br />
# Click on <code>Classlist Editor</code> in the left panel again<br />
<br />
# When you enter a new student, by default their <code>Student ID</code> is used as their password. We'll change this now.<br />
# Select yourself with a check mark and then check <code>Give new password to Selected users</code> or just check <code>Give new password to All users</code> (as a safely mechanism you can not change the password for the user you are logged in as, currently <code>admin</code>, this way) and then click <code>Take Action!</code><br />
# Enter the password, check <code>Save changes</code> and then click <code>Take Action!</code><br />
# Finally give yourself <code>professor</code> privilges by selecting yourself with a check mark, checking <code>Edit Selected users</code> and then clicking <code>Take Action!</code> (or by just clicking on the "pencil" next to your login name which is a much faster way to edit classlist data for a single user)<br />
# Now at the far right change <code>Permission Level</code> from <code>student</code> to <code>professor</code><br />
# Check <code>Save changes</code> and then click <code>Take Action!</code><br />
<br />
At some point you will probably want to hide the <code>admin</code> course so that it is not listed on the WeBWorK home page. As we noted above the <code>modelCourse</code>, which is already hidden, is not a real course so you will get an error message if you try to log into it. This is a good reason to hide it. The <code>modelCourse</code> is very useful as a model (hence its name) for setting up other courses. The <code>admin</code> course is used for administering WeBWorK and even though regular users can not log into it (you did change the <code>admin</code> password, didn't you!!), it a little bit cleaner and safer to hide it from prying eyes. <br />
To hide a course place a file named <code>hide_directory</code> in the course directory and it will not show up in the courses list on the WeBWorK home page. It will still appear in the Course Administration listing. If you do this you will still be able to access the <code>admin</code> course using the URL <code>http://yourserver.yourschool.edu/webwork2/admin</code> but you will not see a link for it on the WeBWorK home page <code>http://yourserver.yourschool.edu/webwork2</code> . Let's hide the <code>admin</code> course.<br />
<br />
$ sudo cp /opt/webwork/courses/modelCourse/hide_directory /opt/webwork/courses/admin<br />
password:<your password><br />
<br />
<br />
Now goto <code>http://yourserver.yourschool.edu/webwork2</code> and no course will be listed.<br />
<br />
== Starting and Stopping Apache, MySQL and the GNOME desktop GUI ==<br />
If you make changes to the system, you will have to restart <code>apache2</code> before the changes take effect. On rare occasions you may need to restart <code>MySQL</code>. <br />
=== Starting and Stopping Apache ===<br />
You have to run these commands as <code>root</code>.<br />
<br />
To start or restart (i.e. stop and then start) the <code>apache2</code> webserver run the command <br />
<br />
$ sudo apache2ctl graceful<br />
password:<your password><br />
<br />
To stop the Apache webserver run the command <br />
<br />
$ sudo apache2ctl stop<br />
password:<your password><br />
<br />
You can also start or stop apache2, listed as <code>Web server (apache2)</code>, by using the GUI interface.<br />
# Select <code>System</code>, <code>Administration</code> and then <code>Services</code><br />
# Scroll down to <code>Web server (apache2)</code><br />
# If <code>apache2</code> is running, uncheck its check box and click <code>Close</code> to stop it<br />
# If <code>apache2</code> is stopped, check its check box and click <code>Close</code> to start it<br />
<br />
Another method is to use the <code>init.d</code> script <code>apache2</code>. Run<br />
$ sudo /etc/init.d/apache2<br />
password:<your password><br />
and you will get a list of allowed commands (<code>start</code>, <code>stop</code>, <code>restart</code>, etc).<br />
<br />
Note that in an earlier version of Ubuntu I found using the GUI interface somewhat unreliable.<br />
<br />
=== Starting and Stopping MySQL ===<br />
You have to run these commands as <code>root</code>.<br />
<br />
To start the <code>MySQL</code> server run the command <br />
<br />
$ sudo /etc/init.d/mysql start<br />
password:<your password><br />
<br />
To stop the <code>MySQL</code> server run the command <br />
<br />
$ sudo /etc/init.d/mysql stop<br />
password: <your password><br />
<br />
To restart the <code>MySQL</code> server run the command <br />
<br />
$ sudo /etc/init.d/mysql restart<br />
password: <your password><br />
<br />
You can also start or stop MySQL, listed as <code>Database server (mysql)</code>, by using the GUI interface.<br />
<br />
# Select <code>Desktop</code>, <code>Administration</code> and then <code>Services</code><br />
# Scroll down to <code>Database server (mysql)</code><br />
# If <code>mysql</code> is running, uncheck its check box and click <code>Close</code> to stop it<br />
# If <code>mysql</code> is stopped, check its check box and click <code>Close</code> to start it<br />
<br />
=== Starting and stopping the GNOME desktop GUI ===<br />
<br />
The GNOME desktop is automatically started when the system boots. <br />
<br />
To stop <code>GNOME</code> so that you only have a standard terminal window run the following in a standard terminal window<br />
<br />
$ sudo /etc/init.d/gdm stop <br />
password: <your password><br />
<br />
If you stopped <code>GNOME</code> and want to restart it run the following in a standard terminal window<br />
<br />
$ sudo /etc/init.d/gdm start <br />
password: <your password><br />
<br />
==Install the WeBWorK Problem Libraries ==<br />
Before we create a real course we will install the WeBWorK Problem Libraries.<br />
<br />
===Install the National Problem Library ===<br />
The <code>National Problem Library</code> consists of both WeBWorK problems and methods for searching and selecting problems. Also it contains as sub libraries many of the other standard libraries. Normally this library is referred to as the <code>ProblemLibrary</code> but the downloaded CVS directory for it is named <code>database_problems</code>. So the first thing we do is to link <code>ProblemLibrary</code> to <code>database_problems</code>. <br />
<br />
$ cd /opt/webwork/libraries/<br />
$ sudo ln -s database_problems ProblemLibrary<br />
password: <your password><br />
<br />
Next we have to edit <code>global.conf</code>.<br />
<br />
$ cd /opt/webwork/webwork2/conf<br />
$ su<br />
Password: <root password><br />
# gedit global.conf<br />
<br />
# Search for <code>problemLibrary</code> and replace <code>$problemLibrary{root} = "";</code> by <br /> <code>$problemLibrary{root} = "/opt/webwork/libraries/ProblemLibrary";</code> <br />
<br />
Then save the file and quit. And return to a regular user<br />
<br />
#exit<br />
$<br />
<br />
We now create a database, called <code>ProblemLibrary</code>, for for the Problem Library.<br />
To do this do the following:<br />
<br />
$ mysql -u root -p mysql<br />
Enter password: &lt;mysql root password&gt;<br />
mysql> CREATE DATABASE ProblemLibrary;<br />
mysql> GRANT SELECT ON ProblemLibrary.* TO webworkWrite@localhost;<br />
mysql> exit<br />
Bye<br />
$ <br />
<br />
Update mysql<br />
<br />
$ NPL-update<br />
<br />
This has to convert a lot of data (around 14600 files) so please be patient; it can take a long time.<br />
<br />
If at some time in the future you want to upgrade the Problem Library, the process<br />
is simpler. Optionally remove the previous copy of the<br />
library, unpack the new copy in the same place, and run NPL-update.<br />
<br />
===Set up the Rochester and Union Libraries ===<br />
<br />
First we need to edit <code>global.conf</code> one last time<br />
<br />
$ cd /opt/webwork/webwork2/conf<br />
$ su<br />
Password: <root password><br />
# gedit global.conf<br />
<br />
# Search for <code>courseFiles{problibs}</code> and scroll down several lines to the line <br /> <code># rochesterLibrary =&gt; "Rochester",</code><br />
# Uncomment this line (i.e. remove the <code>#</code>) so it becomes <br /> <br />
&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp; <code>rochesterLibrary =&gt; "Rochester",</code><br />
# Directly below this line add the line <br /> <br />
&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp; <code>unionLibrary =&gt; "Union",</code><br />
# Search for <code>macrosPath</code> and scroll down several lines to the line <br /> <code>$pg{directories}{macros},</code><br />
# After this line add the line: <br /> <code>'/opt/webwork/libraries/database_problems/macros/Union',</code> <br />
<br />
Don't forget the coma (<code>,</code>) at the end of these lines. Then save the file and quit.<br />
<br />
Since we have edited <code>global.conf</code> a lot and this is a very critical file, it would be a good idea to run<br />
<br />
<br />
# exit<br />
$ diff global.conf global.conf.dist<br />
<br />
and check that you haven't made any mistakes (e.g. by introducing an inadvertant line break, etc).<br />
<br />
We next put links to the Rochester and Union Libraries in the <code>modelCourse</code> so that when we create courses copying templates from the <code>modelCourse</code>, these libraries will be available. Skip this step if you usually only want to use National Problem Library.<br />
<br />
$ cd /opt/webwork/courses/modelCourse/templates/<br />
$ sudo ln -s /opt/webwork/libraries/database_problems/Union unionLibrary<br />
password: <your password><br />
$ sudo ln -s /opt/webwork/libraries/database_problems/Rochester rochesterLibrary<br />
<br />
If you want to put another library into the <code>modelCourse</code>, just do the analogous thing. If you just want the additional library in a particular course, add the link in the <code>templates</code> directory of that course. If you look in the directory <code>/opt/webwork/libraries/database_problems/</code> you might find other libraries that are not yet listed in <code>global.conf</code> (like <code>Union</code> above) and these can be added in the same way we added <code>Union</code>. Usually they do not require additional macros like <code>Union</code> did. Finally if you add a library with non standard symbols in the name (e.g. <code>uva-statLibrary</code>) you have to use single quotes when adding it to <code>global.conf</code>, e.g. <br><br />
&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp; <code>'uva-statLibrary' => "UVA-Stat",</code> <br><br />
It's easier to just avoid such names.<br />
<br />
==Create Your First Actual Course ==<br />
<br />
Now log into the <code>admin</code> course ( <code>http://yourserver.yourschool.edu/webwork2/admin</code> ) as yourself or <code>admin</code> and <br />
# click on <code>Add Course</code><br />
# For <code>Course ID</code> enter <code>myTestCourse</code><br />
# For <code>Course Title</code> enter <code>My Test Course</code><br />
# Enter your institution<br />
# Leave <code>Add WeBWorK administrators to new course</code> checked<br />
# Add an additional instructor if you wish<br />
# Copy templates from: <code>modelCourse</code> (the default action)<br />
# Select sql_single for the database layout.<br />
# Click on <code>Add Course</code><br />
# Click <code>Log into myTestCourse</code><br />
<br />
and log in either as <code>admin</code> or yourself.<br />
<br />
At some point you will probably want to "hide" <code>myTestCourse</code> from general view but you already know how to do that.<br />
<br />
==Test that Things are Working Properly ==<br />
<br />
We will test out a few important parts of WeBWorK. If you run into problems, you should look at the Apache error log which is located at <code>/var/log/apache2/error.log</code>.<br />
<br />
Click on <code>Hmwk Sets Editor</code> on the <code>Main Menu</code>. Then select (by clicking the circle button) <code>Import</code>, select <code>setDemo.def</code> from the <code>from</code> drop down list and select <code>all current users</code> from the <code>assigning this set to</code> drop down list. Then hit <code>Take Action!</code><br />
<br />
Now click on <code>Homework Sets</code> on the <code>Main Menu</code> and click on <code>Demo</code>. Then look at the problems. Mathematical equations should be typeset. If not, edit the file <code>Constants.pm</code> in the directory <code>/opt/webwork/webwork2/lib/WeBWorK</code>. Change the line <code>$WeBWorK::PG::ImageGenerator::PreserveTempFiles = 0;</code> to <code>...::PreserveTempFiles = 1;</code>. Then restart Apache and view the first couple problems or some new ones. Then look in the directory <code>/opt/webwork/webwork2/tmp/</code>. <code>cd</code> to one of the <code>ImageGenerator.../tmp/</code> directories and look at the error and log files there. When you fix the problem remember to edit <code>...::PreserveTempFiles = 1;</code> back to 0 and restart Apache or you will be saving a lot of unnecessary files. Another useful trick is to try downloading a hard copy of an assignment and then (assuming there are errors) looking at the various log files that are linked to on the output page.<br />
<br />
When you continue looking at problems you will get an error when you try to look at Problem 6 because we have not 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 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). <br />
<br />
Next click on <code>Prob. List</code> to bring back the Problem List Page and click on <code>Download a hardcopy of this homework set</code>. The page is a little complicated because you are a professor but you can just scroll to the bottom and click on <code>Generate hardcopy for selected users and selected sets</code>. You will get an error (because of the bad Problem 6) but just click <code>Download Hardcopy</code> to get what was generated. Also you can see links to various <br />
informational files that are available if you run into problems (normally these files are removed if there are no errors).<br />
<br />
Another thing to do is to use <code>Email</code> on the <code>Main Menu</code>. Again this page is a little complicated because you can do a lot of things with it (including mail merge) but at this point just select yourself in the list to the right and hit <code>Send Email</code> at the bottom. You should receive two emails. One is the message you just sent and the other is an email with subject "WeBWorK email sent" giving information on your mailing. <br />
<br />
As a final test click on <code>Library Browser</code> on the <code>Main Menu</code>. Click <code>Problem Library </code><br />
and select a <code>Subject</code>, <code>Chapter</code> and <code>Section</code> and then hit <code>View Problems</code>. The first 20 of your selected problems will be displayed. You can also test that you can access any additional Problem Libraries that you installed.<br />
<br />
If all the above tests work, you can be pretty confident that WeBWorK is working properly.<br />
<br />
Go back to <code>Hmwk Sets Editor</code> on the <code>Main Menu</code>. Then select (by clicking the circle button) <code>Import</code>, select <code>setOrientation.def</code> from the <code>from</code> drop down list and select <code>all current users</code> from the <code>assigning this set to</code> drop down list. Then hit <code>Take Action!</code>. Then go through the Orientation problems. This is a good first set to use for introducing students to WeBWorK.<br />
<br />
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.<br />
Click on <code>Classlist Editor</code> on the <code>Main Menu</code>.<br />
Then select (by clicking the circle button) <code>Add 1 student(s)</code>and hit <code>Take Action!</code>. Add one student, say Jane Smith, with <code>Student ID</code> <code>1234</code> and <code>Login Name</code> <code>jsmith</code>.<br />
Jane Smith's initial password will be her <code>Student ID</code> <code>1234</code>. Now login as Jane Smith and play around a little.<br />
<br />
==Optional Configurations==<br />
'''Optional A''' stores WeBWorK's "temporary" files in a separate partition. <br />
'''Optional B''' installs and configures a lightweight webserver to serve static files.<br />
'''Optional C''' configures Apache so that access to WeBWorK will be through SSL.<br />
<br />
===Implement Optional A (wwtmp)===<br />
<br />
Now is the time to implement '''Optional A''' if you choose to do so. Actually you can do this at any time and your active courses will continue to function seemingly without change. The only change behind the scenes will be that temporary files will be stored in a different location.<br />
<br />
First we set the group and permissions for the <code>wwtmp</code> directory<br />
<br />
$ su<br />
<root password><br />
# cd /var/www<br />
# chgrp wwdata wwtmp<br />
# chmod ug+w wwtmp<br />
# chmod g+s wwtmp<br />
<br />
Next we have to edit <code>global.conf</code> so that WeBWorK uses the new <code>wwtmp</code> directory. Since we have a working WeBWorK system, first we make a backup copy of <code>global.conf</code>.<br />
<br />
<br />
# cd /opt/webwork/webwork2/conf<br />
# cp global.conf global.bak1<br />
# gedit global.conf<br />
<br />
Now edit <code>global.conf</code>. Find the lines <br />
<br />
$webworkDirs{htdocs_temp} = "$webworkDirs{htdocs}/tmp";<br />
$webworkURLs{htdocs_temp} = "$webworkURLs{htdocs}/tmp";<br />
and replace them by <br />
#$webworkDirs{htdocs_temp} = "$webworkDirs{htdocs}/tmp";<br />
#$webworkURLs{htdocs_temp} = "$webworkURLs{htdocs}/tmp";<br />
$webworkDirs{htdocs_temp} = '/var/www/wwtmp';<br />
$webworkURLs{htdocs_temp} = '/wwtmp';<br />
<br />
Next find the lines <br />
<br />
$courseDirs{html_temp} = "$courseDirs{html}/tmp";<br />
$courseURLs{html_temp} = "$courseURLs{html}/tmp";<br />
and replace them by <br />
#$courseDirs{html_temp} = "$courseDirs{html}/tmp";<br />
#$courseURLs{html_temp} = "$courseURLs{html}/tmp";<br />
$courseDirs{html_temp} = "/var/www/wwtmp/$courseName";<br />
$courseURLs{html_temp} = "/wwtmp/$courseName";<br />
<br />
Then save the file and quit. If you look at the <code>wwtmp</code> directory you will find it empty but after you restart apache and then access some WeBWorK problems, you will find temporary directories and files in <code>wwtmp</code>. Remember your have to restart apache for these changes to take effect.<br />
<br />
===Implement Optional B (lighttp)===<br />
<br />
As is the case for '''Optional A''' you can implement '''Optional B''' at any time and your active courses will continue to function seemingly without change. The only change behind the scenes will be that static images and pages will be served by a light weight web server.<br />
<br />
First we install the light weight webserver <code>lighttp</code><br />
<br />
# Open the <code>Synaptic Package Manager</code> (select <code>System</code>, <code>Administration</code>, <code>Synaptic Package Manager</code>). <br />
# Select <code>Search</code> <br />
# Search for <code>lighttp</code> and select it<br />
# In the pop up window <code>Mark additional required changes?</code> click <code>Mark</code> to accept the requirements.<br />
# Now click <code>Apply</code> and <code>Apply</code> again to confirm the changes.<br />
<br />
You can now quit the <code>Synaptic Package Manager</code>.<br />
<br />
Now we configure <code>lighttp</code>. First let's make a backup of the configuration file.<br />
<br />
<br />
$ su<br />
<root password><br />
# cd /etc/lighttpd<br />
# cp lighttpd.conf lighttpd.conf.bak1<br />
<br />
Now edit <code>lighttpd.conf</code>. <br />
<br />
# gedit lighttpd.conf<br />
<br />
Uncomment the line<br />
# "mod_status",<br />
so it becomes<br />
"mod_status",<br />
<br />
Search for the line<br />
server.document-root = "/var/www/"<br />
and under this line add the line<br />
alias.url = ("/webwork2_files/" => "/opt/webwork/webwork2/htdocs/")<br />
<br />
Apache2 is listening on port 80 so we set lighttp to listen on port 81. Find the line<br />
# server.port = 81<br />
and uncomment it <br />
server.port = 81<br />
<br />
Finally uncomment the line<br />
# status.status-url = "/server-status"<br />
so it becomes<br />
status.status-url = "/server-status"<br />
Then save the file and quit.<br />
<br />
Now restart lighttp<br />
<br />
$su<br />
<root password><br />
# /etc/init.d/lighttpd restart<br />
# exit<br />
$<br />
<br />
Note that you can just run <code>/etc/init.d/lighttpd</code> to get a list of all options.<br />
<br />
Now test your server by connecting to<br />
"http://localhost:81/" and/or connecting to your<br />
server from a browser on a remote machine. You should see the page '''It works!''' indicating that lighttp is running.<br />
<br />
You can check lighttp's status by connecting to<br />
"http://localhost:81/server-status" using a browser on your machine or from to "http://yourserver.yourschool.edu:81/server-status" from a browser on a remote machine.<br />
<br />
The Server-Status page doesn't indicate that lighttp is the web server, but it's certainly different than apache's Server-Status page "http://localhost/server-status".<br />
<br />
Next we configure WeBWorK to take advantage of lighttp.<br />
<br />
First let's make a backup copy of <code>global.conf</code> so that we can easily back out of these changes if necessary.<br />
<br />
# cd /opt/webwork/webwork2/conf<br />
# cp global.conf global.bak2<br />
<br />
<br />
Now edit <code>global.conf</code>. Note that while '''Optional B''' is independent of '''Optional A''', we assume most people implementing '''Optional B''' will have already implemented '''Optional A'''. Therefore we give instructions for editing <br />
global.conf assuming that '''Optional A''' has been implemented. If this is not the case, modify the instructions below accordingly. Also replace <code>yourserver.yourschool.edu</code> with the correct address.<br />
<br />
# gedit global.conf<br />
<br />
Find the line<br />
$webwork_htdocs_url = "/webwork2_files";<br />
and replace it by<br />
#$webwork_htdocs_url = "/webwork2_files";<br />
$webwork_htdocs_url = 'http://yourserver.yourschool.edu:81/webwork2_files';<br />
<br />
Find the line<br />
$webworkURLs{htdocs_temp} = '/wwtmp'<br />
and replace it by<br />
#$webworkURLs{htdocs_temp} = '/wwtmp';<br />
$webworkURLs{htdocs_temp} = 'http://yourserver.yourschool.edu:81/wwtmp';<br />
<br />
Find the line<br />
$courseURLs{html_temp} = "/wwtmp/$courseName";<br />
and replace it by<br />
#$courseURLs{html_temp} = "/wwtmp/$courseName";<br />
$courseURLs{html_temp} = "http://yourserver.yourschool.edu:81/wwtmp/$courseName";<br />
<br />
Then save the file and quit.<br />
<br />
Now restart apache and lighttp.<br />
<br />
$ sudo apache2ctl graceful<br />
password:<your password><br />
$ sudo /etc/init.d/lighttpd restart<br />
<br />
To test things go to your test course <code>http://yourserver.yourschool.edu/webwork2/myTestCourse/</code>. Before you login right click on the WeBWorK icon in the upper left hand corner of the login page. The click on Properties (or whatever is appropriate on your browser) and check that the image is being served from port 81 (something like <code>http://yourserver.yourschool.edu:81/webwork2_files/images/webwork_rectangle.png</code>. Then log into your course and view a problem with typeset equations (e.g. Problem 1 of the Demo set). Again right click on the typeset equation and check that the image is being served from port 81.<br />
<br />
===Implement Optional C (SSL)===<br />
'''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.<br />
<br />
I cribbed these directions from several sources, the main one being http://www.akadia.com/services/ssh_test_certificate.html.<br />
<br />
We will create and work in a <code>tmp</code> directory.<br />
<br />
$ cd<br />
$ mkdir tmp<br />
$ cd tmp<br />
<br />
First we create an RSA Private Key.<br />
<br />
$openssl genrsa -des3 -out server.key 1024<br />
<br />
When you are asked for a <code>pass phrase</code>, enter a phrase which we refer to as <code>&lt;my pass phrase&gt;</code> and then confirm it. Next generate a Certificate Signing Request<br />
openssl req -new -key server.key -out server.csr<br />
<br />
Enter the requested information. '''Important:''' when you are prompted for the <code>Common Name</code> enter your server's fully qualified domain name, something like <code>yourserver.yourschool.edu</code>. You can leave the last two items <br />
A challenge password []:<br />
An optional company name []:<br />
blank.<br />
<br />
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.<br />
<br />
$ cp server.key server.key.bak1<br />
$ openssl rsa -in server.key.bak1 -out server.key<br />
<br />
Next we generate a self-signed certificate which is good for 365 days<br />
<br />
$ openssl x509 -req -days 365 -in server.csr -signkey server.key -out server.crt<br />
<br />
Now we become root, move these files, and set their group and permission.<br />
<br />
$ su<br />
<root password><br />
# mv server.crt /etc/ssl/private<br />
# mv server.key /etc/ssl/private<br />
# cd /etc/ssl/private<br />
# chgrp ssl-cert server.*<br />
# chmod 640 server.*<br />
<br />
Next we enable the <code>mod_ssl</code> module<br />
# a2enmod ssl<br />
<br />
Now we have to configure Apache to use SSL.<br />
# cd /etc/apache2/sites-enabled/<br />
# cp default default.bak1<br />
# gedit default<br />
<br />
Replace the first line<br />
NameVirtualHost *<br />
by the two lines<br />
NameVirtualHost *:80<br />
NameVirtualHost *:443<br />
Now edit the next non blank line<br />
<VirtualHost *><br />
changing it to<br />
<VirtualHost *:80><br />
Next copy the entire section <br />
<VirtualHost *:80> <br />
...<br />
</VirtualHost><br />
(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.<br />
Edit the new second<br />
<VirtualHost *:80><br />
changing it to<br />
<VirtualHost *:443><br />
Now at the end of the file just above the line<br />
</VirtualHost><br />
add the three lines<br />
SSLEngine on<br />
SSLCertificateFile /etc/ssl/private/server.crt<br />
SSLCertificateKeyFile /etc/ssl/private/server.key<br />
Then save the file and quit.<br />
Finally we restart Apache<br />
# apache2ctl graceful<br />
and test things. Connect to https://yourserver.yourschool.edu/webwork2/mtTestCourse<br />
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). <br />
<br />
Assuming that everything is working, the last thing we do is set things up so that requests to http://yourserver.yourschool.edu/webwork2/ are automatically redirected to https://yourserver.yourschool.edu/webwork2/.<br />
<br />
# gedit default<br />
<br />
In the <br />
<VirtualHost *:80><br />
section just above the line<br />
ScriptAlias /cgi-bin/ /usr/lib/cgi-bin/<br />
add the line<br />
Redirect permanent /webwork2 https://yourserver.yourschool.edu/webwork2<br />
where of course you should edit <code>yourserver.yourschool.edu</code> appropriately.<br />
Then save the file and quit.<br />
Restart Apache<br />
# apache2ctl graceful<br />
and try connecting to http://yourserver.yourschool.edu/webwork2/. The real connection should be through https://yourserver.yourschool.edu/webwork2/.<br />
<br />
==Where to go From Here ==<br />
<br />
You should play around with <code>myTestCourse</code> e.g. click on <code>Library Browser</code> and browse the <code>Problem Library</code> and also the <code>Rochester</code> and <code>Union</code> libraries.<br />
<br />
Look at http://webhost.math.rochester.edu/webworkdocs/docs/courseadmin/usingwebwork<br />
<br />
Read [[Course Administration]] for more information about creating courses.<br />
<br />
Consult [[Category:Administrators]] for other WeBWorK documentation for system administrators.<br />
<br />
-- Main.ArnoldPizer - 15 May 2008 <br /><br />
<br />
[[Category:Installation Manuals]]</div>Xiong Chiamiovhttps://webwork.maa.org/mediawiki_new/index.php?title=User_talk:Apizer&diff=4121User talk:Apizer2008-07-03T19:48:51Z<p>Xiong Chiamiov: New page: I thought I'd drop you a note that I'm hoping to go through the 2.4 on Ubuntu installation guide and add alternate instructions for all the GUI work for those of us who have headless serve...</p>
<hr />
<div>I thought I'd drop you a note that I'm hoping to go through the 2.4 on Ubuntu installation guide and add alternate instructions for all the GUI work for those of us who have headless servers (or aren't on location with them). It can also be quite a bit faster much of the time, and considering all the stuff you have to go through to install WW, I don't think it'll hurt them to learn to use apt-get/aptitude. [[User:Xiong Chiamiov|Xiong Chiamiov]] 15:48, 3 July 2008 (EDT)</div>Xiong Chiamiovhttps://webwork.maa.org/mediawiki_new/index.php?title=Installation_Manual_for_2.4_on_Ubuntu_8.04&diff=3267Installation Manual for 2.4 on Ubuntu 8.042008-07-03T19:43:40Z<p>Xiong Chiamiov: /* Starting and Stoping Apache, MySQL and the GNOME desktop GUI */ stoping -> stopping, ocassions -> occasions</p>
<hr />
<div>These instructions cover the installation of the Ubuntu Linux 8.04 operating system and WeBWorK 2.4 from scratch. <br />
<br />
They 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.<br />
<br />
== Notation ==<br />
<br />
First some short comments on notation we will be using. We will use <code>&lt;key&gt;</code> to indicate that you should press a specific key (e.g. <code>&lt;Enter&gt;</code>, <code>&lt;Tab&gt;</code>, <code>&lt;F12&gt;</code>, etc.). Sometimes we will also use e.g. <code>&lt;root password&gt;</code> to indicate you have to enter the root password.<br />
<br />
<code>^</code> will indicate the <code>&lt;Ctrl&gt;</code> key so e.g. <code>^X</code> is really shorthand for <code>&lt;Ctrl&gt; &lt;X&gt;</code>, i.e. press the Ctrl key and hit the X key.<br />
<br />
We will give references to specific versions of software, e.g. httpd-2.2.4.tar.gz rather than the more general httpd-2.x.x.tar.gz. In most cases you should be able to use the latest stable version but we have only tested the versions listed.<br />
<br />
== Installing the Ubuntu 8.04 Linux Operating System ==<br />
<br />
===Installation CD ===<br />
Obtain the <code>Desktop Edition, Alternate</code> installation DVD/CD set. Connect to http://www.ubuntu.com/ for information. On the download page http://www.ubuntu.com/getubuntu/download make sure you check the box for <code>Check here if you need the alternate desktop CD. This CD does not include the Live CD, instead it uses a text-based installer</code>. For example you can use wxDownload Fast or BitTorrent to download an ISO image of the installation CD and then burn your own installation CD. 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/7.04/MD5SUMS). wxDownload Fast automatically calculates the MD5 checksums which is convenient. I have had good luck downloading from mirrors.kernel.org but your experience may differ. These instructions will assume you have the installation CD but installing from a commercial DVD/CD set or from the net should be essentially identical.<br />
<br />
Place the installation CD in your DVD/CD drive and reboot your computer from the DVD drive. You may have to press <code>&lt;F12&gt;</code> 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.<br />
<br />
First select <code>English</code> by just hitting <code>&lt;Enter&gt;</code>.<br />
<br />
You will see a list of options. <br />
<br />
# If you want hit <code>&lt;F1&gt;</code> to obtain help and see additional boot methods<br />
# You can just hit <code>&lt;Enter&gt;</code> to accept the default install method except in the following situation<br />
# If your network has DHCP enabled but you want to setup your server with a static IP address, then hit <code>&lt;F6&gt;</code> and on the <code>Boot OPtions</code> line move the cursor before <code>quiet --</code> and type <code>netcfg/disable_dhcp=true</code> , leave a space before <code>quiet</code> and then hit <code>&lt;Enter&gt;</code><br />
# A succession of pages follow, for each select the obvious option and hit <code>&lt;Enter&gt;</code>. For example my obvious options are <code>English</code>, <code>United States</code>, <code>&lt;No&gt;</code>, <code>USA</code> and <code>USA</code> <br />
# The system will than scan your CD and load various components<br />
# If your system has multiple network interfaces, you will be asked to select the one to be used during the installation (which will usually be a hard wired ethernet connection)<br />
# Unless you entered the <code>netcfg/disable_dhcp=true</code> boot option above, the system will try to configure your network using DHCP. If you have DHCP, your network interface will be set up automatically. If you don't have DHCP, automatic network configuration will fail quickly (or just hit <code>&lt;Enter&gt;</code> to <code>Cancel</code> if you are impatient). Then hit <code>&lt;Enter&gt;</code> to <code>Continue</code><br />
<br />
'''Manual network configuration'''. If your network interface was set up automatically by DHCP, you can skip the rest of this paragraph. Otherwise you will have to enter your machine's static ip address, etc. To do this<br />
# Select <code>Configure network manually</code><br />
# Enter your computer's IP address and use <code>&lt;Tab&gt;</code> to select <code>Continue</code><br />
# The <code>netask</code> is probably OK as it but another possibility may be 255.255.0.0<br />
# Enter the ip address of your gateway router. Ubuntu makes a good guess at this, but your network may be set up differently.<br />
# Next enter the ip address(es) of up to 3 nameservers separated by spaces (at a minimum you have to enter the ip address one nameserver)<br />
# Enter the name of your server<br />
# Enter the domain name for the domain your server sits on (e.g. math.myschool.edu)<br />
# This completes the static ip address setup<br />
<br />
Now select your time zone and wait for the clock to be configured<br />
<br />
===Optional Configurations===<br />
<br />
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.<br />
<br />
'''Optional A''' creates a separate partition 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 means that it is easier and faster to back up other partitions and skip backing up unnecessary files.<br />
<br />
'''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.<br />
<br />
'''Optional C''' configures Apache so that access to WeBWorK will be through an encrypted Secure Sockets Layer (SSL) with an https: URL.<br />
<br />
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.<br />
<br />
===Partition disks===<br />
Next comes the <code>Partition disks</code> 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. <br />
<br />
'''Optional A''': The default partitioning scheme creates just two partitions, a root (<code>/</code>) partition and a swap partition. Here we will create those and an additional partition for WeBWorK's temporary files.<br />
<br />
# On the <code>Partition disks</code> page use <code>&lt;Tab&gt;</code> to select <code>Go Back</code> and then select <code>Partition disks</code> <br />
# Use the down arrow to select your disk (<code>sda</code>)<br />
# On the <code>You have selected an entire device to partition...</code> page select <code>Yes</code> to the question <code>Create new empty partition table on this device</code><br />
# On the <code>This is an overview...</code> page select <code>FREE SPACE</code><br />
# On the <code>How to use this free space</code> page select <code>Create a new partition</code><br />
# 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 (<code>/</code>) partition. Actually if you are going through the trouble of doing this, you probably will want to research other partitioning recommendations.<br />
# On the <code>The maximum size you can use...</code> page enter the size for your root (<code>/</code>) partition and <code>Continue</code><br />
# Select <code>Primary</code> for the type of the new partition<br />
# Select <code>Beginning</code> for the location of the new partition<br />
# Select <code>/</code> for the Mount point of the new partition and then select <code>Done setting up the partition</code><br />
<br />
Now we repeat the process for the partition which will hold WeBWorK's temporary files.<br />
# On the <code>This is an overview...</code> page select <code>FREE SPACE</code><br />
# On the <code>How to use this free space</code> page select <code>Create a new partition</code><br />
# On the <code>The maximum size you can use...</code> page enter the size for WeBWorK's temporary files partition. As we said 25 GB for every 1,000 students should be ample. Then <code>Continue</code><br />
# Select <code>Logical</code> for the type of the new partition<br />
# Select <code>Beginning</code> for the location of the new partition<br />
# Select <code>Mount point</code> and then hit <code>&lt;Enter&gt;</code><br />
# Select <code>Enter manually</code> and then hit <code>&lt;Enter&gt;</code><br />
# For the <code>Mount point for this partition</code> enter <code>/var/www/wwtmp</code> and <code>Continue</code><br />
# Then select <code>Done setting up the partition</code><br />
<br />
Finally we set up the swap partition<br />
# On the <code>This is an overview...</code> page select <code>FREE SPACE</code><br />
# On the <code>How to use this free space</code> page select <code>Create a new partition</code><br />
# On the <code>The maximum size you can use...</code> 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 <code>Continue</code><br />
# Select <code>Logical</code> for the type of the new partition<br />
# Select <code>Beginning</code> for the location of the new partition<br />
# Select <code>Use as</code> and then hit <code>&lt;Enter&gt;</code><br />
# Select <code>swap area</code> and then hit <code>&lt;Enter&gt;</code><br />
# Then select <code>Done setting up the partition</code><br />
<br />
Finally <br />
# Review your changes and<br />
# Select <code>Finish partitioning and write changes to disk</code> and then hit <code>&lt;Enter&gt;</code><br />
# Select <code>Yes</code> to confirm the changes<br />
<br />
===Base Installation===<br />
# Now the base installation takes place --- this takes a short time<br />
# Enter yourself as a user (with user name and password). Note this account will function partially as the <code>root</code> account so you might want to pick a different username and password than you regularly use. <br />
# You can probably leave the HTTP proxy information blank<br />
# Now sit back and relax while a lot of software is installed --- this takes awhile<br />
<br />
The final step is to install the boot loader. I have a non standard setup and for some reason I had trouble installing the Grub boot loader but Lilo worked fine. Almost certainly, Grub will work fine for you<br />
<br />
===Continue Installation ===<br />
After this finishes the system will eject the CD and ask you to reboot. <br />
<br />
# Log into your account <br />
# Accept any available updates. You may see a little notification icon (it has a arrow on it) to the right of your name in the upper right hand corner of the screen --- click on it. Alternately you can select <code>System</code>, <code>Administration</code>, <code>Update Manager</code>. Click <code>install Updates</code>. You may have to enter the <code>&lt;your password&gt;</code> which functions as the <code>&lt;root password&gt;</code> . Follow any instructions, e.g. you may be told to reboot as soon as the installation is completed (to reboot, select <code>System</code>, <code>Quit</code> and then <code>Restart</code>)<br />
<br />
===Test Browser and Keyboard ===<br />
<br />
After reboot and login, click on <code>Applications</code>, <code>Internet</code>, <code>Firefox Web Browser</code> (or just click the Firefox icon at the top of the screen) and you should be connected to the world. <br />
Goto <br />
http://webwork.maa.org/wiki/Installation_Manual_for_2.4_on_Ubuntu_8.04<br />
where you can view this document and, if you want, copy commands that you need (see below).<br />
<br />
If something is wrong and you are not connected to the web, the first thing to do is check that you entered the correct network information.<br />
# Select <code>System</code>, <code>Administration</code>, <code>Network</code><br />
# Click on <code>Unlock</code><br />
# Enter <code>&lt;your password&gt;</code> and click <code>Authenticate</code><br />
# Select <code>Wired connection</code> and click <code>Properties</code><br />
# Check that all the entries are correct and edit them if they are not<br />
# Then click <code>OK</code><br />
# Next click on <code>DNS</code> and check the name server entries and correct if necessary<br />
# Click on <code>Close</code> to close <code>Network settings</code><br />
Your network connection should start up almost immediately. If you are still having problems it's time to investigate further or seek help.<br />
<br />
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. Click <code>System</code>, <code>Preferences</code>, <code>Keyboard</code> and then increase the delay time interval and hit <code>Close</code>.<br />
<br />
== Terminal Window Notation and Use ==<br />
<br />
Before installing and configuring additional software, we need to talk about terminal windows.<br />
<br />
To open a terminal window click <code>Applications</code>, <code>Accessories</code> and then select <code>Terminal</code>.<br />
<br />
In a terminal window some commands will have to be run as root whereas<br />
others should be run as a regular user. We will use # to indicate<br />
that the command is to be run as root e.g.<br />
<br />
# perl -MCPAN -e shell<br />
<br />
and $ to indicate that the command is to be run as a normal user e.g.<br />
<br />
$ cp .bashrc .bashrc.bak1<br />
<br />
To execute the above commands you have to hit <code>&lt;Enter&gt;</code>. We'll just assume this. <br />
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.<br />
<br />
The bash shell which you will be using has a number of very<br />
convenient features.<br />
<br />
One is command and file name completion. If you are typing (e.g.<br />
<code>ch</code>) and hit <code>&lt;tab&gt;</code> bash will complete the command or filename if it is<br />
unambiguous (or more precisely it will complete as much as possible).<br />
If there are multiple possibilities (as in the case of <code>ch</code>) nothing will<br />
happen (except you may hear a beep) and you can type more letter(s) and hit <code>&lt;tab&gt;</code> again. Or you can<br />
hit <code>&lt;tab&gt;</code> a second time and you will see a list of all possible<br />
completions. E.g. entering <code>ch&lt;tab&gt;&lt;tab&gt;</code> gives a list of possible<br />
completions and <code>ch&lt;tab&gt;g&lt;tab&gt;</code> (or <code>chg&lt;tab&gt;</code>) gives <code>chgrp</code>, the change group command. This<br />
is very fast and convenient and it also leads to fewer typing errors.<br />
<br />
Another useful shortcut is the command history. Using the up and down<br />
arrow keys will bring up previous commands which can be edited and then<br />
executed. If you are repeating a command or entering a command which<br />
is similar to a previous one, this is very useful.<br />
<br />
You can copy commands from these instructions (with <code>copy</code> from the Edit dropdown list or <code>^C</code>) and paste them into a terminal window<br />
(with <code>paste</code> from the Edit dropdown list or <code>&lt;Shift&gt; &lt;Ctrl&gt; &lt;V&gt;</code>). However typing yourself using command completion is probably just as fast except if a command is long.<br />
<br />
By default Ubuntu has no password set for the root user. To gain root access you have to type in your own user password. This is the password you set for the first user while installing Ubuntu. However we will<br />
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:<br />
<br />
$ sudo passwd<br />
Password: <your password><br />
<br />
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'''.<br />
<br />
Enter new UNIX password: <root password><br />
Retype new UNIX password: <root password><br />
passwd: Password updated successfully<br />
$<br />
<br />
To test this <br />
<br />
$ su<br />
Password: <root password><br />
# whoami<br />
root<br />
#exit<br />
$<br />
<br />
Finally perhaps a safer way to run commands as <code>root</code> is to use the <code>sudo</code> command<br />
<br />
$ sudo <command><br />
Password: <your password><br />
<br />
After you enter the password the command is executed. For a certain period (maybe 5 minutes) you can execute additional <code>sudo</code> commands without reentering <code>&lt;your password&gt;</code>. A log of all <code>sudo</code> commands is kept (I don't know where). In these instructions for the most part we will not use <code>sudo</code>, but keep it in mind for other times that you have to become <code>root</code> in order to execute a few commands (e.g. restarting <code>Apache</code>).<br />
<br />
Note that for certain GUI tools such as the <code>Synaptic Package Manager</code> that require root access, the password required is <code>&lt;your password&gt;</code>, the password for the first account you set up, not the new <code>&lt;root password&gt;</code>.<br />
<br />
For our next terminal window task create a <code>downloads</code> directory where we will keep copies of downloaded software.<br />
<br />
$ cd<br />
$ mkdir downloads<br />
<br />
==Ubuntu Software Packages ==<br />
<br />
Our next task is to install a number of Ubuntu software packages.<br />
<br />
# Select <code>System</code>, <code>Administration</code> and then <code>Synaptic Package Manager</code>. You will have to enter the <code>&lt;your password&gt;</code>. The <code>Synaptic Package Manager</code> window will open<br />
# Click on <code>Reload</code> to bring the package information up to date<br />
<br />
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 <code>libnet-ldap-perl</code> and then just give the list of required packages.<br />
<br />
# Select <code>Search</code> <br />
# Under <code>Look in:</code> select <code>Name</code>. The default <code>Description and Name</code> sometimes returns too many possibilities<br />
# We are searching for <code>libnet-ldap-perl</code> so enter <code>ldap-perl</code> (or something similar; you can copy and paste from this document if you want) and click on <code>Search</code><br />
# This should result in 3 possibilities. Select and Mark for Installation (by double clicking or checking and then selecting <code>Mark for Installation</code>) <code>libnet-ldap-perl</code>. You will see a pop up window <code>Mark additional required changes?</code> and you should always click <code>Mark</code> to accept the requirements.<br />
# Follow this basic procedure for all the packages listed below<br />
<br />
Here is the list of Debian packages that need to be installed. See [[Installation Manual for 2.4]] for a short explanation of what most of these packages do. <br />
<br />
# <code>apache2</code><br />
# <code>apache2-mpm-prefork</code><br />
# <code>cvs</code><br />
# <code>dvipng</code><br />
# <code>libapache2-request-perl</code><br />
# <code>libdatetime-perl</code><br />
# <code>libdbd-mysql-perl</code><br />
# <code>libemail-address-perl</code><br />
# <code>libextutils-xsbuilder-perl</code><br />
# <code>libgd-gd2-perl</code><br />
# <code>libmail-sender-perl</code><br />
# <code>libnet-ldap-perl</code><br />
# <code>libossp-uuid-perl</code><br />
# <code>libsql-abstract-perl</code><br />
# <code>libstring-shellquote-perl</code><br />
# <code>libtimedate-perl</code><br />
# <code>libxml-parser-perl</code><br />
# <code>libxml-writer-perl</code><br />
# <code>mysql-server-5.0</code><br />
# <code>netpbm</code><br />
# <code>openssh-server</code><br />
# <code>preview-latex-style</code><br />
# <code>tetex-bin</code><br />
# <code>tetex-extra</code><br />
<br />
When I do this I see on the bottom of <code>Synaptic Package Manager</code> window <code>82 to install/upgrade</code>, <code>1 to remove</code>. Your numbers may differ slightly. <br />
Now click <code>Apply</code> and <code>Apply</code> again to confirm the changes. You will be asked several times to enter a<br />
<code>New password for the MySQL "root" user</code>; just hit <code>&lt;Enter&gt;</code> which gives the default blank password. We will fix this and several other MySQL security issues below.<br />
<br />
That completes the set up of your base Ubuntu system. You can quit the <code>Synaptic Package Manager</code>.<br />
<br />
<br />
If you would prefer to install all of these packages in one fell swoop, run this command as root:<br />
<br />
<code># aptitude install apache2 apache2-mpm-prefork cvs dvipng libapache2-request-perl libdatetime-perl libdbd-mysql-perl libemail-address-perl libextutils-xsbuilder-perl libgd-gd2-perl libnet-ldap-perl libossp-uuid-perl libsql-abstract-perl libnet-ldap-perl libsql-abstract-perl libstring-shellquote-perl libtimedate-perl libxml-parser-perl libxml-writer-perl mysql-server-5.0 netpbm openssh-server preview-latex-style tetex-bin tetex-extra</code><br />
<br />
== Installing Perl Modules ==<br />
We now have to install several additional Perl modules which unfortunately are not available from the Debian package system.<br />
<br />
=== Testing Perl Modules ===<br />
To test if a Perl module is installed and working on your system, issue the following command, replacing <code>Module</code> with the name of the module:<br />
<br />
$ perl -MModule -e 'print "installed!\n"'<br />
<br />
If the module is installed you will see <code>installed!</code>. If not you will see at lot of gibberish. E.g. at this stage in our installation process <code>CPAN</code> is installed and <code>MXML::Parser::EasyTree</code> is not so<br />
<br />
$ perl -MCPAN -e 'print "installed!\n"'<br />
<br />
yields<br />
<br />
installed!<br />
<br />
and<br />
<br />
$ perl -MXML::Parser::EasyTree -e 'print "installed!\n"'<br />
<br />
yields<br />
<br />
Can't locate XML/Parser/EasyTree.pm in @INC (@INC contains: <br />
/etc/perl /usr/local/lib/perl/5.8.8 /usr/local/share/perl/5.8.8<br />
...<br />
<br />
=== Installing Additional Perl Modules from CPAN ===<br />
<br />
Be aware that in rare cases you might have to <br />
as root run<br />
<br />
$ su<br />
<root password><br />
# unset LANG<br />
# exit<br />
$<br />
<br />
since otherwise the installation of some modules (Module::Build is an example) may fail.<br />
<br />
First we will set up CPAN. For this you have to be root.<br />
<br />
$ su<br />
<root password><br />
# perl -MCPAN -e shell<br />
<br />
Since this is the first time you are using CPAN it will ask you <code>Are you ready for manual configuration?</code> <br />
Respond <code>no</code> and that should be it. <br />
<br />
Next we add at least one mirror and reload the index. A list of mirrors can be found at http://mirrors.cpan.org. To add the mirror ftp://mirrors.kernel.org/pub/CPAN and reload the index do the following. For me, a slow and inaccurate typist, copying (<code>^C</code>) and pasting (<code>&lt;Shift&gt; &lt;Ctrl&gt; &lt;V&gt;</code>) is much faster.<br />
<br />
cpan> o conf urllist push ftp://mirrors.kernel.org/pub/CPAN<br />
cpan> reload index<br />
<br />
Note that one time this failed when I tried to do it in the evening but when I tried again the next morning it worked fine. Now we update CPAN itself<br />
<br />
cpan> install Bundle::CPAN<br />
<br />
and always hit <code>&lt;Enter&gt;</code> to accept the defaults when prompted. This can be a long process with many long pauses. Please be patient. <br />
When you again see the <br />
<br />
cpan><br />
<br />
prompt enter<br />
<br />
cpan> reload cpan<br />
cpan> o conf commit<br />
<br />
Now install the following modules<br />
<br />
cpan> install XML::Parser::EasyTree Iterator Iterator::Util Net::IP <br />
<br />
and in case you are prompted accept all defaults by just hitting <code>&lt;Enter&gt;</code>. <br />
Note that with more than one module to install, we just list them after <code>install</code> separated by spaces.<br />
<br />
When you again see the <br />
<br />
cpan><br />
<br />
prompt enter<br />
<br />
cpan> exit<br />
#<br />
<br />
=== Installing Additional Perl Modules from Source ===<br />
At one point in time (August 2006), the installation of <code>DateTime</code> using CPAN was broken. Currently <code>DateTime</code> 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. <br />
<br />
'''IMPORTANT:''' With Debian we have already installed <code>DateTime</code> 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.<br />
<br />
Now we give the example of installing <code>DateTime</code> from source. As we said you can skip this part.<br />
<br />
Goto http://search.cpan.org/,<br />
search for <code>DateTime</code> and click on <code>DateTime</code>. Then near the top right download <code>DateTime-0.36.tar.gz</code> and save it to disk. Move it to your <code>downloads</code> directory. Then<br />
<br />
$ cd <br />
$ cd downloads<br />
$ tar -zvxf DateTime-0.36.tar.gz<br />
$ cd DateTime-0.36/<br />
<br />
<br />
$ perl Makefile.PL<br />
$ make<br />
$ make test<br />
<br />
If <code>make test</code> indicates something is missing you will have to install that. In fact in the case of <code>DateTime</code>, you would see that quite a few things are missing.<br />
<code>DateTime</code> requires the additional modules <code>version</code> , <code>Module::Build</code> , <code>Class::Singleton</code> , <code>DateTime::TimeZone</code> and <code>DateTime::Locale</code> . We could install these using CPAN<br />
<br />
# perl -MCPAN -e shell<br />
cpan> install version Module::Build Class::Singleton DateTime::TimeZone DateTime::Locale<br />
cpan> exit<br />
# exit<br />
$<br />
<br />
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<br />
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 <code>package/file.pm</code> was not found, you should serach for and install <code>package::file</code> since perl modules use a double colon (<code>::</code>) as a directory separator.<br />
<br />
Assuming all is OK<br />
<br />
$su<br />
<root password><br />
# make install<br />
# exit<br />
$<br />
<br />
Finally you should definitely test that the module (e.g. <code>DateTime</code>) was installed sucessfully<br />
<br />
$ perl -MDateTime -e 'print "installed!\n"'<br />
<br />
If you see <br />
<br />
installed!<br />
<br />
you can celebrate.<br />
<br />
== Apache 2 and mod_perl ==<br />
<br />
First we have to enable a couple Apache modules. Acting as <code>root</code> in a terminal window enter<br />
<br />
# a2enmod apreq<br />
# a2enmod info<br />
<br />
Next we make a copy of the configuration files for safekeeping. <br />
<br />
# cd /etc/apache2/mods-available<br />
# cp info.conf info.conf.bak1<br />
# cp status.conf status.conf.bak1<br />
<br />
Now we will edit configuration files <code>info.conf</code> and <code>status.conf</code> to allow us to view information about the setup and performance of the web server. Note that this is not absolutely necessary but it can be very useful. You can use your favorite editor but we will give instructions assuming you are using <code>gedit</code>. Note that you have to be root to edit these files. First we edit <code>info.conf</code><br />
<br />
# cd /etc/apache2/mods-available<br />
# gedit info.conf<br />
<br />
I suggest you allow access to server information from e.g. your department domain. To do this uncomment (i.e. remove the <code>#</code> from) <br />
# Allow from .example.com<br />
and then replace <code>.example.com</code> by <code>.math.yourschool.edu</code><br />
where of course you should edit <code>.math.yourschool.edu</code> appropriately. <br />
<br />
Then save the file and quit (<code>Save</code> and <code>File</code>, <code>Quit</code>).<br />
<br />
Now we edit <code>status.conf</code><br />
<br />
# cd /etc/apache2/mods-available<br />
# gedit status.conf<br />
<br />
After the comments at the top and above the <code><Location /server-status></code> line enter<br />
<br />
ExtendedStatus On<br />
<br />
Now edit the <br />
# Allow from .example.com<br />
line just as you did for <code>info.conf</code>.<br />
Then save the file and quit<br />
<br />
Now we have to set your server's fully qualified domain name. <br />
# Select <code>System</code>, <code>Administration</code>, <code>Network</code><br />
# Click on <code>Unlock</code><br />
# Enter <code>&lt;your password&gt;</code> and click <code>Authenticate</code><br />
# Click on <code>General</code><br />
# Under <code>Host name</code> enter <code>your_server_name</code> (if it's not already there)<br />
# Then under <code>Domain name</code> enter your server's domain name, something like <code>department.school.edu</code><br />
<br />
Next<br />
# Click on <code>Hosts</code><br />
#There should also be an entry with your server's IP address (if not you should add one)<br />
# Select the entry with your server's IP address and click <code>Properties</code><br />
# Under Aliases you should see your server's fully qualified domain name, something like <code>your_server_name.department.school.edu</code><br />
# Add or edit these entries if they are not correct<br />
# Then click <code>OK</code><br />
# And click <code>Close</code> to close <code>Network settings</code><br />
<br />
You can check these settings by running the commands<br />
<br />
$ hostname --fqdn<br />
<br />
and <br />
<br />
$ hostname<br />
<br />
The first respond with the fully qualified domain name and the second with just <code>your_server_name</code>.<br />
<br />
If the command <code>hostname --fqdn</code> returns <code>Unknown host</code> do the following:<br />
<br />
# Select <code>System</code>, <code>Administration</code>, <code>Network</code><br />
# Click on <code>Unlock</code><br />
# Enter <code>&lt;your password&gt;</code> and click <code>Authenticate</code><br />
# Click on <code>Hosts</code><br />
# Select the entry with your server's IP address and click <code>Properties</code><br />
# Under Aliases you should see your server's fully qualified domain name, something like <code>your_server_name.department.school.edu</code><br />
# Select the entry <code>127.0.0.1</code> and click <code>Properties</code><br />
# Under Aliases make sure you have the following entries in order<br />
## first your server's fully qualified domain name, something like <code>your_server_name.department.school.edu</code><br />
## second your server's name, something like <code>your_server_name</code><br />
## third <code>localhost</code><br />
# Click <code>Add</code> and add an entry with <code>IP address</code> <code>127.0.1.1</code> and under <code>Aliases</code> put your server's fully qualified domain name, something like <code>your_server_name.department.school.edu</code><br />
# Then click <code>OK</code><br />
# And click <code>Close</code> to close <code>Network settings</code><br />
<br />
Then check again by running the commands<br />
<br />
$ hostname --fqdn<br />
<br />
and <br />
<br />
$ hostname<br />
<br />
Note that if your server can not find its fully qualified domain name, certain tools (such as the Synaptic Package Manager) will not start.<br />
<br />
Now restart Apache<br />
<br />
$su<br />
<root password><br />
# apache2ctl graceful<br />
# exit<br />
$<br />
<br />
and test your server by connecting to<br />
"http://localhost/" and/or connecting to your<br />
server from a browser on a remote machine. You should see the page '''It works!''' indicating that Apache is running.<br />
<br />
You can check Apache's status by connecting to<br />
"http://localhost/server-status" using a browser on your machine or from a browser on a remote machine in the math.yourschool.edu domain.<br />
<br />
Further test Apache by connecting to<br />
"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 <br />
information about Apache. In particular under <code>Server Settings</code> you should see<br />
<br />
Server Version: Apache/2.2.8 (Ubuntu) mod_apreq2-20051231/2.6.0 mod_perl/2.0.3 Perl/v5.8.8<br />
<br />
indicating that both <code>mod_apreq2</code> and <code>mod_perl</code> are installed.<br />
<br />
If you have problems now or in the future, a good first thing to do is to look at the Apache error log which is located at <code>/var/log/apache2/error.log</code>. In the directory <code>/var/log/apache2/</code> you can "less" through the error log (<code>less error.log</code>), look at the last few entires (<code>tail error.log</code>) or run the command <code>tail -f error.log</code> which will display new error messages as they are appended to the file. Use <br />
<code>^C</code> to break out of <code>tail -f</code> .<br />
<br />
== Checking MySQL ==<br />
<br />
First check that MySQL is running by <br />
<br />
$ mysql -u root<br />
<br />
You should see<br />
<br />
Welcome to the MySQL monitor. Commands end with ; or \g.<br />
Your MySQL connection id is 1<br />
Server version: 5.0.51a-3ubuntu5 (Ubuntu)<br />
<br />
Type 'help;' or '\h' for help. Type '\c' to clear the buffer.<br />
<br />
mysql> <br />
<br />
Enter <code>exit</code> to exit<br />
<br />
mysql> exit<br />
Bye<br />
$<br />
<br />
== Reboot and Test ==<br />
<br />
Now reboot the system (<code>System</code>, <code>Quit</code>, <code>Restart</code>).<br />
<br />
Now connect to<br />
"http://localhost/" using a browser on your machine and/or to your<br />
server from a browser on a remote machine. You should see the page '''It Works''' indicating that Apache is running.<br />
<br />
This is also a good time to check that 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 <code>Keyboard Interactive</code> to the list of "Authentication methods" under "Authentication" if it's not already there. <br />
<br />
Finally test that MySQL is running.<br />
<br />
$ mysql -u root<br />
...<br />
mysql> <br />
mysql> exit<br />
Bye<br />
$<br />
<br />
Currently the MySQL password is empty so we didn't need a password.<br />
We will take care of that now.<br />
<br />
== MySQL Security Issuses ==<br />
As initially set up, MySQL is a very open system. There are anonymous accounts with full privileges for some databases and the root accounts are not password protected. See e.g. http://dev.mysql.com/doc/refman/5.0/en/default-privileges.html for information on this. We recommend removing the anonymous accounts and giving passwords to the root accounts. There are three root accounts, one is <code>root@localhost</code>, one is <code>root@127.0.0.1</code> and the third is <code>root@host_name</code> where <code>host_name</code> is the name of your server. To find this name, do the following <br />
<br />
$ mysql -u root<br />
mysql> SELECT Host, User, Password FROM mysql.user;<br />
<br />
You will see a table with six entries. For <code>localhost</code> you will see three Users, <code>root</code> and <code>debian-sys-maint</code> and one with an empty name (the anonymous user). The other listed Host (with a <code>root</code> user and also one with an empty name) is the name of your server which we will denote by <code>host_name</code>. <br />
<br />
First we will remove the anonymous accounts. <br />
<br />
mysql> DELETE FROM mysql.user WHERE User = <nowiki>''</nowiki>;<br />
mysql> FLUSH PRIVILEGES;<br />
<br />
Now using the up arrow key repeat the command<br />
<br />
mysql> SELECT Host, User, Password FROM mysql.user;<br />
<br />
and you should get a table with only four users (three <code>root</code> and one <code>debian-sys-maint</code>). <br />
<br />
Now we will assign a password to these <code>root</code> accounts. <br />
<br />
In the third command below, replace <code>host_name</code> with the name of the server host. In all commands replace <code>newpwd</code> with your choosen MySQL <code>root</code> password. As was said above, '''Do not forget what you enter here'''. Also remember that this is the password for the MySQL <code>root</code> user, not the Ubuntu linux system <code>root</code> user. Below we refer to this as <code>&lt;mysql root password&gt;</code><br />
<br />
mysql> UPDATE mysql.user SET password=PASSWORD('newpwd') WHERE host='localhost' and user='root';<br />
mysql> UPDATE mysql.user SET password=PASSWORD('newpwd') WHERE host='127.0.0.1' and user='root';<br />
mysql> UPDATE mysql.user SET password=PASSWORD('newpwd') WHERE host='host_name' and user='root';<br />
mysql> FLUSH PRIVILEGES;<br />
<br />
Now use your up arrow key to run the command<br />
<br />
mysql> SELECT Host, User, Password FROM mysql.user;<br />
<br />
and you should see that all three users now have passwords (which will be displayed in encrypted form).<br />
<br />
Then exit MySQL<br />
<br />
mysql> exit<br />
Bye<br />
$<br />
<br />
<br />
and test that all is well:<br />
<br />
$ sudo /etc/init.d/mysql restart<br />
password:<your password><br />
$ mysql -u root -p <br />
Enter Password: <mysql root password><br />
<br />
You should see<br />
<br />
Welcome to the MySQL monitor ...<br />
mysql><br />
<br />
Enter<br />
<br />
mysql> SELECT Host, User, Password FROM mysql.user;<br />
<br />
and you should see encrypted passwords for all three accounts. Note that the way MySQL is set up, you can only gain access to the <code>localhost</code> account, not to the <code>host_name</code> account but setting a password for the <code>host_name</code> account is a safer thing to do in case the set up gets changed. Now exit MySQL<br />
<br />
mysql> exit<br />
Bye<br />
$ <br />
<br />
and congratulate yourself. You are now ready for the next and hopefully easy part, installing WeBWorK.<br />
<br />
== Downloading the WeBWorK System Software and Problem Libraries ==<br />
We are finally at the point where we can start downloading and installing WeBWorK. We will use CVS to download WeBWorK. This is easy and it will also make it easy to update the system in the future. Note that the following are rather long commands; it is much easier to copy (<code>^C</code>) them from this document and paste (<code>&lt;Shift&gt; &lt;Ctrl&gt; &lt;V&gt;</code>) them in a terminal window<br />
<br />
$ cd<br />
$ cd downloads<br />
<br />
$ cvs -d :pserver:anoncvs@cvs.webwork.rochester.edu:/webwork/cvs/system checkout -r rel-2-4-dev webwork2 pg<br />
$ cvs -d :pserver:anoncvs@cvs.webwork.rochester.edu:/webwork/cvs/asu checkout database_problems<br />
<br />
The first download gives you the latest released version with patches (don't be misled by the <code>dev</code> extension --- this is not a development version).<br />
The second download contains the WeBWorK National Problem Library. This now includes the Rochester and Union Libraries along with others as sunlibraries. There is quite a bit of overlap between these libraries but now you system is loaded with many thousands of WeBWorK problems (over 13,000 in the National Problem Library main collection alone).<br />
<br />
== Installing WeBWorK ==<br />
=== Move the System into the Required Directories ===<br />
As <code>root</code> create a <code>webwork</code> directory under <code>/opt</code> and move directories there. <br />
<br />
$ su<br />
<root password><br />
# mkdir /opt/webwork<br />
# mv webwork2 /opt/webwork/<br />
# mv pg /opt/webwork/<br />
<br />
Now create the <code>courses</code> and <code>libraries</code> directories under <code>webwork</code> and copy and move content there.<br />
<br />
# mkdir /opt/webwork/courses<br />
# mkdir /opt/webwork/libraries<br />
# mv database_problems/ /opt/webwork/libraries/<br />
# cd /opt/webwork/webwork2/courses.dist<br />
# cp *.lst /opt/webwork/courses/<br />
# cp -r modelCourse/ /opt/webwork/courses/<br />
<br />
=== Setting Permissions ===<br />
<br />
The PG installation directory and files should be owned by root and not writable by other users:<br />
<br />
# cd /opt/webwork/pg<br />
# chown -R root:root .<br />
# chmod -R u+rwX,go+rX .<br />
<br />
Most WeBWorK directories and files should also be owned by root and not writable by other users:<br />
<br />
# cd /opt/webwork/webwork2<br />
# chown -R root:root .<br />
# chmod -R u+rwX,go+rX .<br />
<br />
Certain data directories need to be writable by the web server. These are <code>DATA</code>, <code>courses</code>, <code>htdocs/tmp</code>, <code>logs</code>, and <code>tmp</code>. It is convenient to give WeBWorK administrators access to these directories as well, so they can perform administrative tasks such as removing temporary files, creating and editing courses from the command line, managing logs, and so on. We will create a new group called <code>wwdata</code>, containing both the WeBWorK administrators and the web server.<br />
<br />
# Select <code>System</code>, <code>Administration</code> and then <code>Users and Groups</code><br />
# Click on <code>Unlock</code><br />
# Enter <code>&lt;your password&gt;</code> and click <code>Authenticate</code><br />
# Select <code>Manage Groups</code><br />
# Click <code>Add Group</code> <br />
# For <code>Group name</code> enter <code>wwdata</code><br />
# Under <code>Group Members</code> select yourself and click <code>OK</code><br />
# Click <code>Close</code><br />
<br />
If there are other users who will also be administering WeBWorK files,<br />
now is a good time to add them. And remember to add them to the <code>wwdata</code> group as above.<br />
<br />
Because system users are not shown by default, we can not simply use the <code>Group Manager</code> to add the Apache2 webserver (which runs as <code>www-data</code>) to the <code>wwdata</code><br />
group so we will do this by hand.<br />
<br />
# cd /etc<br />
# cp group group.bak1<br />
# gedit group<br />
<br />
<br />
# In the gedit window scroll to the last line. <br />
# It should look like <code>wwdata:x:1001:<your userid></code><br />
# Append to this line <code>,www-data</code><br />
# Then Save and Quit<br />
<br />
<br />
<br />
You can check that this succeeded in a terminal window by entering<br />
<br />
# exit<br />
$ id <your userid><br />
<br />
and then you should see <code>wwdata</code> listed under groups. Also<br />
<br />
$ id www-data<br />
<br />
should show wwdata listed under groups. Now we make the WeBWorK directories that need to be writable by the web server have <code>wwdata</code> as their group. The following are rather long commands; you might want to copy them and paste them into your terminal window rather than typing them.<br />
<br />
$ su<br />
<root password><br />
# cd /opt/webwork/webwork2/<br />
# chgrp -R wwdata DATA ../courses htdocs/tmp logs tmp<br />
# chmod -R g+w DATA ../courses htdocs/tmp logs tmp<br />
# find DATA/ ../courses/ htdocs/tmp logs/ tmp/ -type d -a ! -name CVS -exec chmod g+s {} \;<br />
# exit<br />
$<br />
<br />
== Configuring the Shell ==<br />
<br />
To make working with WeBWorK easier, there are a couple of changes you can make to your shell environment.<br />
<br />
Add the WeBWorK <code>bin</code> directory to your path. This will allow you to run WeBWorK command-line utilities without typing the full path to the utility. Goto your home directory and backup your <code>.bashrc</code> file<br />
<br />
$ cd<br />
$ cp .bashrc .bashrc.bak1<br />
<br />
Now edit <code>.bashrc</code><br />
<br />
$ gedit .bashrc<br />
<br />
After the last line add the two lines:<br />
<br />
export PATH=$PATH:/opt/webwork/webwork2/bin<br />
export WEBWORK_ROOT=/opt/webwork/webwork2<br />
<br />
Then save the file and Quit.<br />
<br />
Close your Terminal Window and open a new one so the above changes<br />
take effect. You can check that they have by<br />
<br />
$ echo $PATH<br />
$ echo $WEBWORK_ROOT<br />
<br />
== Checking Module Dependancies ==<br />
<br />
<br />
<br />
WeBWorK includes a script called <code>check_modules.pl</code> that verifies that the needed programs and Perl modules are installed on your system. Run this script to make sure you have installed the required programs and Perl modules.<br />
<br />
$ check_modules.pl apache2<br />
<br />
Scroll up and look through the listing. It should find everything except <code>PHP::Serialization</code>, <code>SOAP::Lite</code>, <code>MIME::Parser</code> and <code>XMLRPC::Lite</code> which are only required if you plan to use WeBWorK with Moodle and <code>tth</code> which is a deprecated display mode. If something is missing (flagged by <code>**</code>), look back through these instructions and/or look at 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.<br />
<br />
== Configuring WeBWorK ==<br />
<br />
=== Making Copies of the Distribution Configuration Files ===<br />
<br />
Before configuring the system, you must make local copies of the <code>global.conf</code> and <code>database.conf</code> configuration files, located in <code>/opt/webwork/webwork2/conf/</code> . Since these are owned by <code>root</code><br />
<br />
$ su<br />
<root password><br />
# cd /opt/webwork/webwork2/conf<br />
# cp global.conf.dist global.conf<br />
# cp database.conf.dist database.conf<br />
<br />
=== Global Configuration ===<br />
<br />
Most WeBWorK configuration is done in the file <code>/opt/webwork2/conf/global.conf</code>. This file provides system-wide configuration settings, and defaults for course settings. Any setting in this file can be overridden in the <code>course.conf</code> file for a particular course. To override a setting for a course, just put the new setting (using the same syntax as is in <code>global.conf</code>) in the <code>course.conf</code> file.<br />
<br />
There are several options that must be set for WeBWorK to work with your system. The rest of the file consists of customization options. Now edit <code>global.conf</code><br />
<br />
# cd /opt/webwork/webwork2/conf<br />
# gedit global.conf<br />
<br />
WeBWorK uses the DateTime module. DateTime is supposed to be able to determine the local timezone itself without you having to enter it but this often fails so it is best to just set it here. For is a list of timezones recognized by DateTime go to<br />
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 <code>DateTime::TimeZone::America::New_York</code> and you should replace <code>$siteDefaults{timezone} = "";</code> by <code>$siteDefaults{timezone} = "America/New_York";</code> <br />
<br />
# Search for <code>$siteDefaults{timezone} = "";</code> and enter your local timezone.<br />
<br />
At this point <code>TtH</code> is a deprecated display mode which we didn't install so we have to remove it from the listof possible display modes. <br />
<br />
# Search for <code>formattedText</code> and comment out the line <code>"formattedText", # format math expressions using TtH</code><br />
so it becomes<br />
<br />
# "formattedText", # format math expressions using TtH<br />
<br />
We need to set a password that WeBWorK uses when it communicates with the MySQL database. Note that this is not the same as the <code>&lt;mysql root password&gt;</code> which is the password the MySQL root user uses.<br />
# Search for <code>$database_password = "";</code> and replace this by <br /> <code>$database_password = "database_password";</code> <br />
where of course you should replace 'database_password' with your own password. Remember this password as we will need it below.<br />
<br />
WeBWorK sends mail in three instances. The PG system sends mail to report answers to questionnaires and free-response problems. The mail merge module is used to send mail to course participants, i.e. to report scores. The feedback module allows participants to send mail to course instructors.<br />
<br />
To send mail, WeBWorK needs the address of an SMTP server. Normally you will use the address of your school's SMTP server. If the local machine is running an SMTP server, use <code>localhost</code>. IMPORTANT: Our instructions above did not install an SMTP server so you will have to install and configue one if you do not use your school's SMTP server. When connecting to the SMTP server, WeBWorK must also send an email address representing the sender of the email (this has nothing to do with the <code>From</code> address on the mail message). Edit the lines<br />
$mail{smtpServer} = 'mail.yourschool.edu'; <br />
$mail{smtpSender} = 'webwork@yourserver.yourschool.edu';<br />
<br />
entering the appropriate information.<br />
<br />
If you want WeBWorK questionnaires or similar things from different courses to be mailed to a central person or persons (e.g. the WeBWorK administrator), edit the lines<br />
<br />
$mail{allowedRecipients} = [<br />
#'prof1@yourserver.yourdomain.edu',<br />
#'prof2@yourserver.yourdomain.edu',<br />
];<br />
<br />
appropriately removing the <code>#</code> and using the professor(s) actual email address(es). In order to have professors from individual courses receive such email, this <br />
should be set in course.conf to the addresses of professors of each course.<br />
<br />
Then save the file and Quit.<br />
<br />
<br />
Now become a regular user again<br />
<br />
# exit<br />
$<br />
<br />
WeBWorK uses a single database, called <code>webwork</code>, for all courses. We will create the <code>webwork</code> database now.<br />
<br />
To do this do the following (before you just copy, paste and hit <code>&lt;Enter&gt;</code> notice that you have to replace <code>database_password</code> with the password you set when editing <code>global.conf</code> above):<br />
<br />
$ mysql -u root -p mysql<br />
Enter password: <mysql root password><br />
mysql> CREATE DATABASE webwork;<br />
mysql> GRANT SELECT, INSERT, UPDATE, DELETE, CREATE, ALTER, DROP, LOCK TABLES ON webwork.* TO webworkWrite@localhost IDENTIFIED BY 'database_password';<br />
mysql> exit<br />
Bye<br />
$ <br />
<br />
where as we said replace <code>database_password</code> with the password you set when editing <code>global.conf</code> above.<br />
<br />
Since version 2.3.0 WeBWorK has an automatic database upgrade system. Rather than manually issuing SQL commands to make changes to the database, or using ad-hoc scripts like wwdb_addgw, there is a single script called <code>wwdb_upgrade</code> that applies any necessary updates. It should be run when creating a new database, and any time you upgrade WeBWorK.<br />
<br />
$ /opt/webwork/webwork2/bin/wwdb_upgrade -v<br />
<br />
=== jsMath Settings ===<br />
<br />
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 <code>webwork2/htdocs/jsMath/jsMath-fonts.tar.gz</code>, and you need to unpack this tarball before jsMath will work properly. Use the command<br />
<br />
$ su<br />
<root password><br />
# cd /opt/webwork/webwork2/htdocs/jsMath<br />
# tar vfxz jsMath-fonts.tar.gz<br />
<br />
This will unpack the archive. Since there are 20,000 tiny files, it can take a little while, so the <code>v</code> 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.<br />
<br />
<br />
== Configuring Apache ==<br />
WeBWorK ships with an Apache config file that needs to linked into your Apache configuration process. The file is named <code>webwork.apache2-config.dist</code> and located in the <code>conf</code> directory. First, copy the file to <code>webwork.apache2-config</code>:<br />
<br />
# cd /opt/webwork/webwork2/conf<br />
# cp webwork.apache2-config.dist webwork.apache2-config<br />
<br />
and now link it into your Apache configuration process<br />
<br />
# cd /etc/apache2/conf.d<br />
# ln -s /opt/webwork/webwork2/conf/webwork.apache2-config webwork.conf<br />
<br />
Then restart Apache <br />
<br />
# apache2ctl graceful<br />
# exit<br />
$<br />
<br />
== Test your configuration ==<br />
<br />
# Test the <code>/webwork2</code> location by visiting <code>http://yourserver.yourschool.edu/webwork2</code>. You should see the WeBWorK home page with no courses listed. Actually the directory <code>/opt/webwork/courses/</code> does contain the <code>modelCourse</code> but the <code>modelCourse</code> is not a real course so you will get an error message if you try to log into it. It will be used a as model for setting up other courses. For this reason <code>/opt/webwork/courses/modelCourse/</code> contains a file named <code>hide_directory</code> and so the <code>modelCourse</code> is not visible.<br />
# Test the <code>/webwork2_files</code> location by visiting <code>http://yourserver.yourschool.edu/webwork2_files</code>. You should see the "WeBWorK Placeholder Page".<br />
# You cannot test the <code>/webwork2_course_files</code> location until you have created a course.<br />
<br />
==If Something is Wrong ==<br />
If something is wrong one of the first things to check is that the config files have been edited correctly (e.g. one time a wrapped line in <code>global.conf</code> caused me problems, another time it was a missing single quote). A quick way to check this is to do a <code>diff</code> between the edited and distributed versions and check that <code>diff</code> reports the changes you made and only those.<br />
<br />
# exit<br />
$<br />
$ cd /etc/apache2/<br />
$ diff apache2.conf apache2.conf.bak1<br />
$ cd /opt/webwork/webwork2/conf/<br />
$ diff global.conf global.conf.dist<br />
$ diff database.conf database.conf.dist<br />
$ diff webwork.apache2-config webwork.apache2-config.dist <br />
<br />
If something is wrong and you fix it, you will have to restart Apache for the changes to take effect<br />
<br />
$ su<br />
<root password><br />
# apache2ctl graceful<br />
# exit<br />
$<br />
<br />
== Create the admin Course ==<br />
<br />
[[Course Administration]] gives information about creating courses. Here we will give explicit instructions for doing this.<br />
<br />
$ su<br />
<root password><br />
# newgrp wwdata<br />
# umask 2<br />
# cd /opt/webwork/courses<br />
# /opt/webwork/webwork2/bin/addcourse admin --db-layout=sql_single --users=adminClasslist.lst --professors=admin<br />
# exit<br />
# exit<br />
$<br />
<br />
Now goto <code>http://yourserver.yourschool.edu/webwork2</code> and should see the WeBWorK home page with <code>Course Adninistration</code> listed at the top. Click on it and login with Username <code>admin</code> and Password <code>admin</code> . This first thing you should do is to click on <code>Password/Email</code> and change <code>admin</code> 's password to something more secure than <code>admin</code> . <br />
<br />
Unless you choose oherwise, users with <code>professor</code> privilges in the <code>admin</code> course (i.e. WeBWorK administrators) will automatically be added to new courses with <code>professor</code> privilges and the same password as in the <code>admin</code> course. Initially the only such user is <code>admin</code> (hopefully you are not confused by the fact that the course <code>admin</code> has a user named <code>admin</code>). It's usually convenient make yourself a WeBWorK administrator. To do this (assuming you are logged in as <code>admin</code> to the <code>admin</code> course at <code>http://yourserver.yourschool.edu/webwork2/admin</code> )<br />
# Click on <code>Classlist Editor</code> in the left panel<br />
# Check <code>Add 1 student(s)</code> and click <code>Take Action!</code><br />
# Enter the appropiate information (you can leave the last three items blank) and click <code>Add Students</code><br />
# Click on <code>Classlist Editor</code> in the left panel again<br />
<br />
# When you enter a new student, by default their <code>Student ID</code> is used as their password. We'll change this now.<br />
# Select yourself with a check mark and then check <code>Give new password to Selected users</code> or just check <code>Give new password to All users</code> (as a safely mechanism you can not change the password for the user you are logged in as, currently <code>admin</code>, this way) and then click <code>Take Action!</code><br />
# Enter the password, check <code>Save changes</code> and then click <code>Take Action!</code><br />
# Finally give yourself <code>professor</code> privilges by selecting yourself with a check mark, checking <code>Edit Selected users</code> and then clicking <code>Take Action!</code> (or by just clicking on the "pencil" next to your login name which is a much faster way to edit classlist data for a single user)<br />
# Now at the far right change <code>Permission Level</code> from <code>student</code> to <code>professor</code><br />
# Check <code>Save changes</code> and then click <code>Take Action!</code><br />
<br />
At some point you will probably want to hide the <code>admin</code> course so that it is not listed on the WeBWorK home page. As we noted above the <code>modelCourse</code>, which is already hidden, is not a real course so you will get an error message if you try to log into it. This is a good reason to hide it. The <code>modelCourse</code> is very useful as a model (hence its name) for setting up other courses. The <code>admin</code> course is used for administering WeBWorK and even though regular users can not log into it (you did change the <code>admin</code> password, didn't you!!), it a little bit cleaner and safer to hide it from prying eyes. <br />
To hide a course place a file named <code>hide_directory</code> in the course directory and it will not show up in the courses list on the WeBWorK home page. It will still appear in the Course Administration listing. If you do this you will still be able to access the <code>admin</code> course using the URL <code>http://yourserver.yourschool.edu/webwork2/admin</code> but you will not see a link for it on the WeBWorK home page <code>http://yourserver.yourschool.edu/webwork2</code> . Let's hide the <code>admin</code> course.<br />
<br />
$ sudo cp /opt/webwork/courses/modelCourse/hide_directory /opt/webwork/courses/admin<br />
password:<your password><br />
<br />
<br />
Now goto <code>http://yourserver.yourschool.edu/webwork2</code> and no course will be listed.<br />
<br />
== Starting and Stopping Apache, MySQL and the GNOME desktop GUI ==<br />
If you make changes to the system, you will have to restart <code>apache2</code> before the changes take effect. On rare occasions you may need to restart <code>MySQL</code>. <br />
=== Starting and Stopping Apache ===<br />
You have to run these commands as <code>root</code>.<br />
<br />
To start or restart (i.e. stop and then start) the <code>apache2</code> webserver run the command <br />
<br />
$ sudo apache2ctl graceful<br />
password:<your password><br />
<br />
To stop the Apache webserver run the command <br />
<br />
$ sudo apache2ctl stop<br />
password:<your password><br />
<br />
You can also start or stop apache2, listed as <code>Web server (apache2)</code>, by using the GUI interface.<br />
# Select <code>System</code>, <code>Administration</code> and then <code>Services</code><br />
# Scroll down to <code>Web server (apache2)</code><br />
# If <code>apache2</code> is running, uncheck its check box and click <code>Close</code> to stop it<br />
# If <code>apache2</code> is stopped, check its check box and click <code>Close</code> to start it<br />
<br />
Another method is to use the <code>init.d</code> script <code>apache2</code>. Run<br />
$ sudo /etc/init.d/apache2<br />
password:<your password><br />
and you will get a list of allowed commands (<code>start</code>, <code>stop</code>, <code>restart</code>, etc).<br />
<br />
Note that in an earlier version of Ubuntu I found using the GUI interface somewhat unreliable.<br />
<br />
=== Starting and Stopping MySQL ===<br />
You have to run these commands as <code>root</code>.<br />
<br />
To start the <code>MySQL</code> server run the command <br />
<br />
$ sudo /etc/init.d/mysql start<br />
password:<your password><br />
<br />
To stop the <code>MySQL</code> server run the command <br />
<br />
$ sudo /etc/init.d/mysql stop<br />
password: <your password><br />
<br />
To restart the <code>MySQL</code> server run the command <br />
<br />
$ sudo /etc/init.d/mysql restart<br />
password: <your password><br />
<br />
You can also start or stop MySQL, listed as <code>Database server (mysql)</code>, by using the GUI interface.<br />
<br />
# Select <code>Desktop</code>, <code>Administration</code> and then <code>Services</code><br />
# Scroll down to <code>Database server (mysql)</code><br />
# If <code>mysql</code> is running, uncheck its check box and click <code>Close</code> to stop it<br />
# If <code>mysql</code> is stopped, check its check box and click <code>Close</code> to start it<br />
<br />
=== Starting and stopping the GNOME desktop GUI ===<br />
<br />
The GNOME desktop is automatically started when the system boots. <br />
<br />
To stop <code>GNOME</code> so that you only have a standard terminal window run the following in a standard terminal window<br />
<br />
$ sudo /etc/init.d/gdm stop <br />
password: <your password><br />
<br />
If you stopped <code>GNOME</code> and want to restart it run the following in a standard terminal window<br />
<br />
$ sudo /etc/init.d/gdm start <br />
password: <your password><br />
<br />
==Install the WeBWorK Problem Libraries ==<br />
Before we create a real course we will install the WeBWorK Problem Libraries.<br />
<br />
===Install the National Problem Library ===<br />
The <code>National Problem Library</code> consists of both WeBWorK problems and methods for searching and selecting problems. Also it contains as sub libraries many of the other standard libraries. Normally this library is referred to as the <code>ProblemLibrary</code> but the downloaded CVS directory for it is named <code>database_problems</code>. So the first thing we do is to link <code>ProblemLibrary</code> to <code>database_problems</code>. <br />
<br />
$ cd /opt/webwork/libraries/<br />
$ sudo ln -s database_problems ProblemLibrary<br />
password: <your password><br />
<br />
Next we have to edit <code>global.conf</code>.<br />
<br />
$ cd /opt/webwork/webwork2/conf<br />
$ su<br />
Password: <root password><br />
# gedit global.conf<br />
<br />
# Search for <code>problemLibrary</code> and replace <code>$problemLibrary{root} = "";</code> by <br /> <code>$problemLibrary{root} = "/opt/webwork/libraries/ProblemLibrary";</code> <br />
<br />
Then save the file and quit. And return to a regular user<br />
<br />
#exit<br />
$<br />
<br />
We now create a database, called <code>ProblemLibrary</code>, for for the Problem Library.<br />
To do this do the following:<br />
<br />
$ mysql -u root -p mysql<br />
Enter password: &lt;mysql root password&gt;<br />
mysql> CREATE DATABASE ProblemLibrary;<br />
mysql> GRANT SELECT ON ProblemLibrary.* TO webworkWrite@localhost;<br />
mysql> exit<br />
Bye<br />
$ <br />
<br />
Update mysql<br />
<br />
$ NPL-update<br />
<br />
This has to convert a lot of data so please be patient; it can take a long time.<br />
<br />
If at some time in the future you want to upgrade the Problem Library, the process<br />
is simpler. Optionally remove the previous copy of the<br />
library, unpack the new copy in the same place, and run NPL-update.<br />
<br />
===Set up the Rochester and Union Libraries ===<br />
<br />
First we need to edit <code>global.conf</code> one last time<br />
<br />
$ cd /opt/webwork/webwork2/conf<br />
$ su<br />
Password: <root password><br />
# gedit global.conf<br />
<br />
# Search for <code>courseFiles{problibs}</code> and scroll down several lines to the line <br /> <code># rochesterLibrary =&gt; "Rochester",</code><br />
# Uncomment this line (i.e. remove the <code>#</code>) so it becomes <br /> <br />
&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp; <code>rochesterLibrary =&gt; "Rochester",</code><br />
# Directly below this line add the line <br /> <br />
&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp; <code>unionLibrary =&gt; "Union",</code><br />
# Search for <code>macrosPath</code> and scroll down several lines to the line <br /> <code>$pg{directories}{macros},</code><br />
# After this line add the line: <br /> <code>'/opt/webwork/libraries/database_problems/macros/Union',</code> <br />
<br />
Don't forget the coma (<code>,</code>) at the end of these lines. Then save the file and quit.<br />
<br />
Since we have edited <code>global.conf</code> a lot and this is a very critical file, it would be a good idea to run<br />
<br />
<br />
# exit<br />
$ diff global.conf global.conf.dist<br />
<br />
and check that you haven't made any mistakes (e.g. by introducing an inadvertant line break, etc).<br />
<br />
We next put links to the Rochester and Union Libraries in the <code>modelCourse</code> so that when we create courses copying templates from the <code>modelCourse</code>, these libraries will be available. Skip this step if you usually only want to use National Problem Library.<br />
<br />
$ cd /opt/webwork/courses/modelCourse/templates/<br />
$ sudo ln -s /opt/webwork/libraries/database_problems/Union unionLibrary<br />
password: <your password><br />
$ sudo ln -s /opt/webwork/libraries/database_problems/Rochester rochesterLibrary<br />
<br />
If you want to put another library into the <code>modelCourse</code>, just do the analogous thing. If you just want the additional library in a particular course, add the link in the <code>templates</code> directory of that course. If you look in the directory <code>/opt/webwork/libraries/database_problems/</code> you might find other libraries that are not yet listed in <code>global.conf</code> (like <code>Union</code> above) and these can be added in the same way we added <code>Union</code>. Usually they do not require additional macros like <code>Union</code> did. Finally if you add a library with non standard symbols in the name (e.g. <code>uva-statLibrary</code>) you have to use single quotes when adding it to <code>global.conf</code>, e.g. <br><br />
&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp; <code>'uva-statLibrary' => "UVA-Stat",</code> <br><br />
It's easier to just avoid such names.<br />
<br />
==Create Your First Actual Course ==<br />
<br />
Now log into the <code>admin</code> course ( <code>http://yourserver.yourschool.edu/webwork2/admin</code> ) as yourself or <code>admin</code> and <br />
# click on <code>Add Course</code><br />
# For <code>Course ID</code> enter <code>myTestCourse</code><br />
# For <code>Course Title</code> enter <code>My Test Course</code><br />
# Enter your institution<br />
# Leave <code>Add WeBWorK administrators to new course</code> checked<br />
# Add an additional instructor if you wish<br />
# Copy templates from: <code>modelCourse</code> (the default action)<br />
# Select sql_single for the database layout.<br />
# Click on <code>Add Course</code><br />
# Click <code>Log into myTestCourse</code><br />
<br />
and log in either as <code>admin</code> or yourself.<br />
<br />
At some point you will probably want to "hide" <code>myTestCourse</code> from general view but you already know how to do that.<br />
<br />
==Test that Things are Working Properly ==<br />
<br />
We will test out a few important parts of WeBWorK. If you run into problems, you should look at the Apache error log which is located at <code>/var/log/apache2/error.log</code>.<br />
<br />
Click on <code>Hmwk Sets Editor</code> on the <code>Main Menu</code>. Then select (by clicking the circle button) <code>Import</code>, select <code>setDemo.def</code> from the <code>from</code> drop down list and select <code>all current users</code> from the <code>assigning this set to</code> drop down list. Then hit <code>Take Action!</code><br />
<br />
Now click on <code>Homework Sets</code> on the <code>Main Menu</code> and click on <code>Demo</code>. Then look at the problems. Mathematical equations should be typeset. If not, edit the file <code>Constants.pm</code> in the directory <code>/opt/webwork/webwork2/lib/WeBWorK</code>. Change the line <code>$WeBWorK::PG::ImageGenerator::PreserveTempFiles = 0;</code> to <code>...::PreserveTempFiles = 1;</code>. Then restart Apache and view the first couple problems or some new ones. Then look in the directory <code>/opt/webwork/webwork2/tmp/</code>. <code>cd</code> to one of the <code>ImageGenerator.../tmp/</code> directories and look at the error and log files there. When you fix the problem remember to edit <code>...::PreserveTempFiles = 1;</code> back to 0 and restart Apache or you will be saving a lot of unnecessary files. Another useful trick is to try downloading a hard copy of an assignment and then (assuming there are errors) looking at the various log files that are linked to on the output page.<br />
<br />
When you continue looking at problems you will get an error when you try to look at Problem 6 because we have not 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 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). <br />
<br />
Next click on <code>Prob. List</code> to bring back the Problem List Page and click on <code>Download a hardcopy of this homework set</code>. The page is a little complicated because you are a professor but you can just scroll to the bottom and click on <code>Generate hardcopy for selected users and selected sets</code>. You will get an error (because of the bad Problem 6) but just click <code>Download Hardcopy</code> to get what was generated. Also you can see links to various <br />
informational files that are available if you run into problems (normally these files are removed if there are no errors).<br />
<br />
Another thing to do is to use <code>Email</code> on the <code>Main Menu</code>. Again this page is a little complicated because you can do a lot of things with it (including mail merge) but at this point just select yourself in the list to the right and hit <code>Send Email</code> at the bottom. You should receive two emails. One is the message you just sent and the other is an email with subject "WeBWorK email sent" giving information on your mailing. <br />
<br />
As a final test click on <code>Library Browser</code> on the <code>Main Menu</code>. Click <code>Problem Library </code><br />
and select a <code>Subject</code>, <code>Chapter</code> and <code>Section</code> and then hit <code>View Problems</code>. The first 20 of your selected problems will be displayed. You can also test that you can access any additional Problem Libraries that you installed.<br />
<br />
If all the above tests work, you can be pretty confident that WeBWorK is working properly.<br />
<br />
Go back to <code>Hmwk Sets Editor</code> on the <code>Main Menu</code>. Then select (by clicking the circle button) <code>Import</code>, select <code>setOrientation.def</code> from the <code>from</code> drop down list and select <code>all current users</code> from the <code>assigning this set to</code> drop down list. Then hit <code>Take Action!</code>. Then go through the Orientation problems. This is a good first set to use for introducing students to WeBWorK.<br />
<br />
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.<br />
Click on <code>Classlist Editor</code> on the <code>Main Menu</code>.<br />
Then select (by clicking the circle button) <code>Add 1 student(s)</code>and hit <code>Take Action!</code>. Add one student, say Jane Smith, with <code>Student ID</code> <code>1234</code> and <code>Login Name</code> <code>jsmith</code>.<br />
Jane Smith's initial password will be her <code>Student ID</code> <code>1234</code>. Now login as Jane Smith and play around a little.<br />
<br />
==Optional Configurations==<br />
'''Optional A''' stores WeBWorK's "temporary" files in a separate partition. <br />
'''Optional B''' installs and configures a lightweight webserver to serve static files.<br />
'''Optional C''' configures Apache so that access to WeBWorK will be through SSL.<br />
<br />
===Implement Optional A (wwtmp)===<br />
<br />
Now is the time to implement '''Optional A''' if you choose to do so. Actually you can do this at any time and your active courses will continue to function seemingly without change. The only change behind the scenes will be that temporary files will be stored in a different location.<br />
<br />
First we set the group and permissions for the <code>wwtmp</code> directory<br />
<br />
$ su<br />
<root password><br />
# cd /var/www<br />
# chgrp wwdata wwtmp<br />
# chmod ug+w wwtmp<br />
# chmod g+s wwtmp<br />
<br />
Next we have to edit <code>global.conf</code> so that WeBWorK uses the new <code>wwtmp</code> directory. Since we have a working WeBWorK system, first we make a backup copy of <code>global.conf</code>.<br />
<br />
<br />
# cd /opt/webwork/webwork2/conf<br />
# cp global.conf global.bak1<br />
# gedit global.conf<br />
<br />
Now edit <code>global.conf</code>. Find the lines <br />
<br />
$webworkDirs{htdocs_temp} = "$webworkDirs{htdocs}/tmp";<br />
$webworkURLs{htdocs_temp} = "$webworkURLs{htdocs}/tmp";<br />
and replace them by <br />
#$webworkDirs{htdocs_temp} = "$webworkDirs{htdocs}/tmp";<br />
#$webworkURLs{htdocs_temp} = "$webworkURLs{htdocs}/tmp";<br />
$webworkDirs{htdocs_temp} = '/var/www/wwtmp';<br />
$webworkURLs{htdocs_temp} = '/wwtmp';<br />
<br />
Next find the lines <br />
<br />
$courseDirs{html_temp} = "$courseDirs{html}/tmp";<br />
$courseURLs{html_temp} = "$courseURLs{html}/tmp";<br />
and replace them by <br />
#$courseDirs{html_temp} = "$courseDirs{html}/tmp";<br />
#$courseURLs{html_temp} = "$courseURLs{html}/tmp";<br />
$courseDirs{html_temp} = "/var/www/wwtmp/$courseName";<br />
$courseURLs{html_temp} = "/wwtmp/$courseName";<br />
<br />
Then save the file and quit. If you look at the <code>wwtmp</code> directory you will find it empty but after you restart apache and then access some WeBWorK problems, you will find temporary directories and files in <code>wwtmp</code>. Remember your have to restart apache for these changes to take effect.<br />
<br />
===Implement Optional B (lighttp)===<br />
<br />
As is the case for '''Optional A''' you can implement '''Optional B''' at any time and your active courses will continue to function seemingly without change. The only change behind the scenes will be that static images and pages will be served by a light weight web server.<br />
<br />
First we install the light weight webserver <code>lighttp</code><br />
<br />
# Open the <code>Synaptic Package Manager</code> (select <code>System</code>, <code>Administration</code>, <code>Synaptic Package Manager</code>). <br />
# Select <code>Search</code> <br />
# Search for <code>lighttp</code> and select it<br />
# In the pop up window <code>Mark additional required changes?</code> click <code>Mark</code> to accept the requirements.<br />
# Now click <code>Apply</code> and <code>Apply</code> again to confirm the changes.<br />
<br />
You can now quit the <code>Synaptic Package Manager</code>.<br />
<br />
Now we configure <code>lighttp</code>. First let's make a backup of the configuration file.<br />
<br />
<br />
$ su<br />
<root password><br />
# cd /etc/lighttpd<br />
# cp lighttpd.conf lighttpd.conf.bak1<br />
<br />
Now edit <code>lighttpd.conf</code>. <br />
<br />
# gedit lighttpd.conf<br />
<br />
Uncomment the line<br />
# "mod_status",<br />
so it becomes<br />
"mod_status",<br />
<br />
Search for the line<br />
server.document-root = "/var/www/"<br />
and under this line add the line<br />
alias.url = ("/webwork2_files/" => "/opt/webwork/webwork2/htdocs/")<br />
<br />
Apache2 is listening on port 80 so we set lighttp to listen on port 81. Find the line<br />
# server.port = 81<br />
and uncomment it <br />
server.port = 81<br />
<br />
Finally uncomment the line<br />
# status.status-url = "/server-status"<br />
so it becomes<br />
status.status-url = "/server-status"<br />
Then save the file and quit.<br />
<br />
Now restart lighttp<br />
<br />
$su<br />
<root password><br />
# /etc/init.d/lighttpd restart<br />
# exit<br />
$<br />
<br />
Note that you can just run <code>/etc/init.d/lighttpd</code> to get a list of all options.<br />
<br />
Now test your server by connecting to<br />
"http://localhost:81/" and/or connecting to your<br />
server from a browser on a remote machine. You should see the page '''It works!''' indicating that lighttp is running.<br />
<br />
You can check lighttp's status by connecting to<br />
"http://localhost:81/server-status" using a browser on your machine or from to "http://yourserver.yourschool.edu:81/server-status" from a browser on a remote machine.<br />
<br />
The Server-Status page doesn't indicate that lighttp is the web server, but it's certainly different than apache's Server-Status page "http://localhost/server-status".<br />
<br />
Next we configure WeBWorK to take advantage of lighttp.<br />
<br />
First let's make a backup copy of <code>global.conf</code> so that we can easily back out of these changes if necessary.<br />
<br />
# cd /opt/webwork/webwork2/conf<br />
# cp global.conf global.bak2<br />
<br />
<br />
Now edit <code>global.conf</code>. Note that while '''Optional B''' is independent of '''Optional A''', we assume most people implementing '''Optional B''' will have already implemented '''Optional A'''. Therefore we give instructions for editing <br />
global.conf assuming that '''Optional A''' has been implemented. If this is not the case, modify the instructions below accordingly. Also replace <code>yourserver.yourschool.edu</code> with the correct address.<br />
<br />
# gedit global.conf<br />
<br />
Find the line<br />
$webwork_htdocs_url = "/webwork2_files";<br />
and replace it by<br />
#$webwork_htdocs_url = "/webwork2_files";<br />
$webwork_htdocs_url = 'http://yourserver.yourschool.edu:81/webwork2_files';<br />
<br />
Find the line<br />
$webworkURLs{htdocs_temp} = '/wwtmp'<br />
and replace it by<br />
#$webworkURLs{htdocs_temp} = '/wwtmp';<br />
$webworkURLs{htdocs_temp} = 'http://yourserver.yourschool.edu:81/wwtmp';<br />
<br />
Find the line<br />
$courseURLs{html_temp} = "/wwtmp/$courseName";<br />
and replace it by<br />
#$courseURLs{html_temp} = "/wwtmp/$courseName";<br />
$courseURLs{html_temp} = "http://yourserver.yourschool.edu:81/wwtmp/$courseName";<br />
<br />
Then save the file and quit.<br />
<br />
Now restart apache and lighttp.<br />
<br />
$ sudo apache2ctl graceful<br />
password:<your password><br />
$ sudo /etc/init.d/lighttpd restart<br />
<br />
To test things go to your test course <code>http://yourserver.yourschool.edu/webwork2/myTestCourse/</code>. Before you login right click on the WeBWorK icon in the upper left hand corner of the login page. The click on Properties (or whatever is appropriate on your browser) and check that the image is being served from port 81 (something like <code>http://yourserver.yourschool.edu:81/webwork2_files/images/webwork_rectangle.png</code>. Then log into your course and view a problem with typeset equations (e.g. Problem 1 of the Demo set). Again right click on the typeset equation and check that the image is being served from port 81.<br />
<br />
===Implement Optional C (SSL)===<br />
'''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.<br />
<br />
I cribbed these directions from several sources, the main one being http://www.akadia.com/services/ssh_test_certificate.html.<br />
<br />
We will create and work in a <code>tmp</code> directory.<br />
<br />
$ cd<br />
$ mkdir tmp<br />
$ cd tmp<br />
<br />
First we create an RSA Private Key.<br />
<br />
$openssl genrsa -des3 -out server.key 1024<br />
<br />
When you are asked for a <code>pass phrase</code>, enter a phrase which we refer to as <code>&lt;my pass phrase&gt;</code> and then confirm it. Next generate a Certificate Signing Request<br />
openssl req -new -key server.key -out server.csr<br />
<br />
Enter the requested information. '''Important:''' when you are prompted for the <code>Common Name</code> enter your server's fully qualified domain name, something like <code>yourserver.yourschool.edu</code>. You can leave the last two items <br />
A challenge password []:<br />
An optional company name []:<br />
blank.<br />
<br />
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.<br />
<br />
$ cp server.key server.key.bak1<br />
$ openssl rsa -in server.key.bak1 -out server.key<br />
<br />
Next we generate a self-signed certificate which is good for 365 days<br />
<br />
$ openssl x509 -req -days 365 -in server.csr -signkey server.key -out server.crt<br />
<br />
Now we become root, move these files, and set their group and permission.<br />
<br />
$ su<br />
<root password><br />
# mv server.crt /etc/ssl/private<br />
# mv server.key /etc/ssl/private<br />
# cd /etc/ssl/private<br />
# chgrp ssl-cert server.*<br />
# chmod 640 server.*<br />
<br />
Next we enable the <code>mod_ssl</code> module<br />
# a2enmod ssl<br />
<br />
Now we have to configure Apache to use SSL.<br />
# cd /etc/apache2/sites-enabled/<br />
# cp default default.bak1<br />
# gedit default<br />
<br />
Replace the first line<br />
NameVirtualHost *<br />
by the two lines<br />
NameVirtualHost *:80<br />
NameVirtualHost *:443<br />
Now edit the next non blank line<br />
<VirtualHost *><br />
changing it to<br />
<VirtualHost *:80><br />
Next copy the entire section <br />
<VirtualHost *:80> <br />
...<br />
</VirtualHost><br />
(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.<br />
Edit the new second<br />
<VirtualHost *:80><br />
changing it to<br />
<VirtualHost *:443><br />
Now at the end of the file just above the line<br />
</VirtualHost><br />
add the three lines<br />
SSLEngine on<br />
SSLCertificateFile /etc/ssl/private/server.crt<br />
SSLCertificateKeyFile /etc/ssl/private/server.key<br />
Then save the file and quit.<br />
Finally we restart Apache<br />
# apache2ctl graceful<br />
and test things. Connect to https://yourserver.yourschool.edu/webwork2/mtTestCourse<br />
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). <br />
<br />
Assuming that everything is working, the last thing we do is set things up so that requests to http://yourserver.yourschool.edu/webwork2/ are automatically redirected to https://yourserver.yourschool.edu/webwork2/.<br />
<br />
# gedit default<br />
<br />
In the <br />
<VirtualHost *:80><br />
section just above the line<br />
ScriptAlias /cgi-bin/ /usr/lib/cgi-bin/<br />
add the line<br />
Redirect permanent /webwork2 https://yourserver.yourschool.edu/webwork2<br />
where of course you should edit <code>yourserver.yourschool.edu</code> appropriately.<br />
Then save the file and quit.<br />
Restart Apache<br />
# apache2ctl graceful<br />
and try connecting to http://yourserver.yourschool.edu/webwork2/. The real connection should be through https://yourserver.yourschool.edu/webwork2/.<br />
<br />
==Where to go From Here ==<br />
<br />
You should play around with <code>myTestCourse</code> e.g. click on <code>Library Browser</code> and browse the <code>Problem Library</code> and also the <code>Rochester</code> and <code>Union</code> libraries.<br />
<br />
Look at http://webhost.math.rochester.edu/webworkdocs/docs/courseadmin/usingwebwork<br />
<br />
Read [[Course Administration]] for more information about creating courses.<br />
<br />
Consult [[Category:Administrators]] for other WeBWorK documentation for system administrators.<br />
<br />
-- Main.ArnoldPizer - 15 May 2008 <br /><br />
<br />
[[Category:Installation Manuals]]</div>Xiong Chiamiovhttps://webwork.maa.org/mediawiki_new/index.php?title=Installation_Manual_for_2.4&diff=1352Installation Manual for 2.42008-07-03T19:34:49Z<p>Xiong Chiamiov: /* Enabling WeBWorK */ added missing letter</p>
<hr />
<div>== Installation instructions for specific operating systems ==<br />
<br />
These manuals offer command-by-command procedures (and fewer choices) than the general instructions. They are targeted at UNIX beginners.<br />
<br />
* [[Installation Manual for 2.4 on Ubuntu 8.04]]<br />
* [[Installation Manual for 2.4 on Fedora 9]]<br />
<br />
[[:Category:Installation_Manuals|More installation manuals...]]<br />
<br />
== Dependencies ==<br />
<br />
=== Apache ===<br />
<br />
WeBWorK supports Apache 1.3 and 2.0. Apache 2.2 is supported experimentally. WeBWorK requires that the <code>mod_alias</code> module be available. Most vendors compile their Apache packages with the necessary features enabled.<br />
<br />
==== Apache 1.3 ====<br />
<br />
* Source: http://httpd.apache.org/<br />
* Debian/Ubuntu: <code>apache</code> <br />
* Red Hat/Fedora: build from source<br />
<br />
==== Apache 2.0 or 2.2 ====<br />
<br />
Apache must be using the <code>prefork</code> MPM. This is because the <code>Safe</code> module, which WeBWorK makes extensive use of, is not threadsafe. This is set at compile time with the <code>--with-mpm=prefork</code> switch to the <code>configure</code> script.<br />
<br />
* Source: http://httpd.apache.org/<br />
* Debian/Ubuntu: <code>apache2</code> with <code>apache2-mpm-prefork</code><br />
* Red Hat/Fedora: build from source; or see below<br />
<br />
''On my Scientific Linux 4 box (i.e., RHEL4) there is no need to recompile apache; mpm-prefork is already set. Of course mod_perl2 must be compiled!'' -- Niels Walet - 13 Mar 2007<br />
<br />
=== Perl ===<br />
<br />
WeBWorK requires Perl 5.6.1 or higher.<br />
<br />
* Source: http://perl.org/<br />
* Debian/Ubuntu: <code>perl</code> (in the default install)<br />
* Red Hat/Fedora: <code>perl</code> (in the default install)<br />
<br />
=== Perl modules ===<br />
<br />
The following Perl modules are required. All are available from [http://cpan.org/ CPAN], and many vendors provide packages of these modules. To see if a module is installed on your system, use the following command. Replace <code>Module</code> with the name of the module.<br />
<br />
$ perl -MModule -e 'print "installed!\n"'<br />
<br />
To check that all modules used by WeBWorK are installed you should run the script:<br />
webwork2/bin/check_modules.pl [apache1|apache2] <br />
or<br />
perl webwork2/bin/check_modules.pl [apache1|apache2]<br />
which checks for the modules needed for either an apache1 or apache2 installation of WeBWorK respectively.<br />
<br />
To install a missing module from CPAN, use the following command as root. Replace <code>Module</code> with the name of the module.<br />
<br />
# perl -MCPAN -e "install Module"<br />
<br />
For more information about using CPAN, consult the [http://cpan.org/misc/cpan-faq.html CPAN FAQ].<br />
<br />
{| border="1"<br />
|-<br />
| '''module'''<br />
| '''Debian/Ubuntu package'''<br />
| '''Gentoo package'''<br />
| '''Fedora Core 7 package'''<br />
|-<br />
| Apache::Request<br/><small>(only if using Apache 1.3.x)<br />
| <code>libapache-request-perl</code><br />
| <br />
| <br />
|-<br />
| Apache2::Request<br/><small>(only if using Apache 2.0.x)<br />
| <code>libapache2-request-perl</code><br />
| <code>libapreq</code><br />
| <code>perl-libapreq2</code><br />
|-<br />
| Data::UUID<br />
| <code>libdata-uuid-perl</code> <br><small>(virtual package, provided by <code>libossp-uuid-perl</code>)</small><br />
| <code>Data-UUID</code><br />
| <code>perl-uuid</code><br />
|-<br />
| Date::Format<br />
| <code>libtimedate-perl</code><br />
| <code>TimeDate</code><br />
| <code>perl-TimeDate</code><br />
|-<br />
| Date::Parse<br />
| <code>libtimedate-perl</code><br />
| <code>TimeDate</code><br />
| <code>perl-TimeDate</code><br />
|-<br />
| DateTime<br />
| <code>libdatetime-perl</code><br />
| <code>DateTime</code><br />
| <code>perl-DateTime</code><br />
|-<br />
| DBD::mysql<br />
| <code>libdbd-mysql-perl</code><br />
| <code>DBD-mysql</code><br />
| <code>perl-DBD-MySQL</code><br />
|-<br />
| Email::Address<br />
| <code>libemail-address-perl</code><br />
| <code>Email-Address</code><br />
| <code>perl-Email-Address</code><br />
|-<br />
| GD<br />
| <code>libgd-gd2-perl</code><br />
| <code>GD</code><br />
| <code>perl-GD</code><br />
|-<br />
| Iterator<br />
| not packaged<br />
| not packaged<br />
| not packaged<br />
|-<br />
| Iterator::Util<br />
| not packaged<br />
| not packaged<br />
| not packaged<br />
|-<br />
| Mail::Sender<br />
| <code>libmail-sender-perl</code><br />
| <code>Mail-Sender</code><br />
| <code>perl-Mail-Sender</code><br />
|-<br />
| SQL::Abstract<br />
| <code>libsql-abstract-perl</code><br />
| unknown<br />
| <code>perl-SQL-Abstract</code> <br />
|-<br />
| String::ShellQuote<br />
| <code>libstring-shellquote-perl</code><br />
| <code>String-ShellQuote</code><br />
| <code>perl-String-ShellQuote</code><br />
|-<br />
| Time::HiRes<br><small>(included in Perl 5.8 and higher)</small><br />
| included in <code>perl</code> package<br />
| unknown<br />
| included in <code>perl</code> package <br />
|-<br />
| XML::Parser<br />
| <code>libxml-parser-perl</code><br />
| <code>libxml-perl</code><br />
| <code>perl-XML-Parser</code> <br />
|-<br />
| XML::Parser::EasyTree<br />
| not packaged<br />
| unknown<br />
| not packaged <br />
|-<br />
| XML::Writer<br />
| <code>libxml-writer-perl</code><br />
| <code>XML-Writer</code><br />
| <code>perl-XML-Writer</code> <br />
|}<br />
<br />
==== DateTime::TimeZone: use version 0.34 or later ====<br />
<br />
Versions of DateTime::TimeZone (a component of DateTime) below 0.34 suffer from a problem with displaying some time zones. Make sure you have version 0.34 or later.<br />
<br />
==== Problems building Time::HiRes ====<br />
<br />
Some users have reported problems building Time::HiRes through CPAN. If this is your experience, try downloading the Time::HiRes tarball from http://search.cpan.org/~jhi/Time-HiRes/ and building it manually (<code>perl Makefile.PL && make && make test && make install</code>).<br />
<br />
==== Problems building Apache::Request or Apache2::Request ====<br />
<br />
Apache::Request is one component of the libapreq library. If you run into problems building it through CPAN, try downloading the libapreq tarball from http://httpd.apache.org/apreq/.<br />
<br />
Apache 2.0.x users should use libapreq2.<br />
<br />
=== mod_perl ===<br />
<br />
WeBWorK uses mod_perl to interface with the Apache server. If compiling mod_perl from source, use the <code>EVERYTHING=1</code> flag to enable all mod_perl features. Most vendors compile their mod_perl packages with this setting enabled.<br />
<br />
==== Apache 1.3 ====<br />
<br />
* Source: http://perl.apache.org/download/<br />
* Debian/Ubuntu: <code>libapache-mod-perl</code> <br />
* Red Hat/Fedora: build from source; see below.<br />
* Gentoo: <code>mod_perl </code><br />
<br />
==== Apache 2.0 ====<br />
<br />
* Source: http://perl.apache.org/download/ <br />
* Debian/Ubuntu: <code>libapache2-mod-perl</code> <br />
* Red Hat/Fedora: build from source <br />
<br />
==== RHEL4/Fedora build notes ====<br />
<br />
''I had to use the flags below to get the compile to work correctly:''<br />
<br />
perl Makefile.PL EVERYTHING=1 DO_HTTPD=1 USE_APACI=1 APACHE_PREFIX=/usr/local/apache<br />
<br />
-- Main.MarkHamrick<br />
<br />
=== MySQL ===<br />
<br />
MySQL 4.0.x or later is required. If you are going to be using the experimental Moodle Integration, MySQL 4.1.x or later is required.<br />
<br />
* Source: http://dev.mysql.com/downloads/ <br />
* Debian/Ubuntu: 4.0.x: <code>mysql-server</code>; 4.1.x: <code>mysql-server-4.1</code><br />
* RHEL4/Fedora: <code>mysql-sever</code>, <code>mysql-client</code> <br />
* Gentoo: <code>mysql </code><br />
<br />
=== LaTeX ===<br />
<br />
WeBWorK requires LaTeX for generating hardcopy output and displaying mathematics graphically. Any standard LaTeX distribution that provides the commands <code>latex</code> and <code>pdflatex</code> should work. We use TeTeX.<br />
<br />
* Source: http://tug.org/tetex/ <br />
* Debian/Ubuntu: <code>tetex-bin</code>, <code>tetex-extra</code> <br />
* Red Hat/Fedora: <code>tetex</code>, <code>tetex-latex</code> <br />
* Gentoo: <code>tetex</code><br />
<br />
=== Netpbm ===<br />
<br />
WeBWorK requires Netpbm to convert images among the GIF, PNG, and EPS formats.<br />
<br />
* Source: http://netpbm.sf.net/ <br />
* Debian/Ubuntu: <code>netpbm</code> <br />
* Red Hat/Fedora: build from source <br />
* Gentoo: <code>netpbm </code><br />
<br />
=== dvipng ===<br />
<br />
WeBWorK uses dvipng to display mathematics graphically. It is only required if you wish to use the <code>images</code> display mode. dvipng requires the <code>preview.sty</code> file from the [http://preview-latex.sf.net/ preview-latex] package.<br />
<br />
* Source: http://dvipng.sf.net/ <br />
* Debian: <code>dvipng</code>, <code>preview-latex-style</code> <br />
* Red Hat/Fedora: <code>preview-latex-common-0.9.1-1.fedora.noarch.rpm</code> <br />
* Gentoo: <code>dvipng</code> <br />
<br />
WeBWorK is initially configured to work with dvipng 1.0 or greater, but can be reconfigured to work with dvipng 0.8 or 0.9. See <code>webwork2/lib/WeBWorK/Constants.pm</code> for details.<br />
<br />
=== TtH ===<br />
<br />
WeBWorK uses TtH to display mathematics as formatted HTML. It is only required if you wish to use the <code>formatted-text</code> display mode.<br />
<br />
* Source: http://hutchinson.belmont.ma.us/tth/ <br />
* Debian:*|| <code>tth</code><br />
* Red Hat/Fedora: build from source <br />
* Gentoo: <code>tth</code><br />
<br />
== Installing the WeBWorK files ==<br />
<br />
WeBWorK is typically installed using CVS. We provide version tags that correspond to each released version of WeBWorK. This ensures that you can maintain a stable system, and experimental upgrades will not be applied to your installation.<br />
<br />
We also provide tarballs for each release. They contain the necessary CVS data to update from CVS at a later date. Choose a tarball if for some reason you do not want to use CVS. Keep in mind that because of the layout of files within the <code>webwork2</code> directory tree, upgrading an existing installation is harder using a tarball than using CVS.<br />
<br />
=== Creating the base directory directory ===<br />
<br />
Before you begin installing files, create a base directory to hold them. We prefer <code>/opt/webwork</code>:<br />
<br />
# mkdir -p /opt/webwork<br />
<br />
To make things easier during the installation, you can give yourself write permission to this directory. That way, you won't have to become root to install the WeBWorK files:<br />
<br />
# chown yourNameHere /opt/webwork<br />
<br />
=== Installing from CVS ===<br />
<br />
Installing from CVS allows you more flexibility in selecting versions of the WeBWorK code between or ahead of releases. You have several options, depending on which release tag you select when accessing the CVS repository.<br />
<br />
==== CVS tags ====<br />
<br />
'''''Released version:''''' By specifying the '''rel-2-4-1''' tag, you get the same version of the code that you would by downloading the WeBWorK 2.4.1 tarball. This is the most conservative option. Updating will have no effect -- this code will never change.<br />
<br />
'''''Released version with patches:''''' By specifying the '''rel-2-4-dev''' tag, you can stay up to date with the latest bug fixes against the released version of WeBWorK 2.4. Few, if any, new features are introduced on a patch branch. We recommend that you choose this option.<br />
<br />
'''''Latest code:''''' If you do not specify a release tag, you will get the latest code. Since this code is a work in progress, it is sometimes unstable or broken. If you require features that are not in a stable release, and are willing to devote more time to keeping your installation running smoothly, this may be the option for you.<br />
<br />
No matter what tag you chose, you can change later by specifying a new tag when running <code>cvs upgrade</code>.<br />
<br />
==== New installation from CVS ====<br />
<br />
If you do not have an existing WeBWorK installation, use the following commands to check out copies of the <code>webwork2</code> and <code>pg</code> modules. If you are prompted for a password, press enter.<br />
<br />
'''''Released version:'''''<br />
<br />
<code>$ cvs -d :pserver:anoncvs@cvs.webwork.rochester.edu:/webwork/cvs/system checkout -r rel-2-4-1 webwork2</code><br/><br />
<code>$ cvs -d :pserver:anoncvs@cvs.webwork.rochester.edu:/webwork/cvs/system checkout -r rel-2-4-0 pg</code><br />
<br />
'''''Released version with patches:'''''<br />
<br />
<code>$ cvs -d :pserver:anoncvs@cvs.webwork.rochester.edu:/webwork/cvs/system checkout -r rel-2-4-dev webwork2 pg</code><br />
<br />
'''''Latest development code:'''''<br />
<br />
<code>$ cvs -d :pserver:anoncvs@cvs.webwork.rochester.edu:/webwork/cvs/system checkout webwork2 pg</code><br />
<br />
The message <code>warning: cannot open /webwork/cvs/system/CVSROOT/val-tags read/write: Permission denied</code> is harmless and should be ignored.<br />
<br />
After checkout finishes, become root and move the directories to the your installation directory. I prefer <code>/opt/webwork</code>:<br />
<br />
# cp -r webwork2 /opt/webwork/webwork2<br />
# cp -r pg /opt/webwork/pg<br />
<br />
==== Upgrading using CVS ====<br />
<br />
If you already have an existing WeBWorK installation, use the following commands to update your exsting files to version 2.4. You may need to become root to run these commands (depending on your permissions situation).<br />
<br />
Take note of the messages that CVS gives during the update. If you have modified files, you may see the message <code>Merging differences between ''version1'' and ''version2'' into _filename_</code>. This indicates that the file in question is updated in WeBWorK 2.4, and since you also made local modifications to it, CVS is attempting to merge the two changed versions.<br />
<br />
If this process fails, because the same parts of the file were modified in both versions, you will see the message <code>rcsmerge: warning: conflicts during merge</code>. If you end up in this situation, you will need to resolve the conflict by editing the file in question. Consult this [http://ximbiot.com/cvs/manual/cvs-1.11.22/cvs_10.html#SEC85 conflicts example] from the CVS manual.<br />
<br />
The message <code>warning: cannot open /webwork/cvs/system/CVSROOT/val-tags read/write: Permission denied</code> is harmless and should be ignored.<br />
<br />
'''''Released version:'''''<br />
<br />
cd /opt/webwork/webwork2<br />
cvs -q update -dP -r rel-2-4-1<br />
cd /opt/webwork/pg<br />
cvs -q update -dP -r rel-2-4-0<br />
<br />
'''''Released version with patches:'''''<br />
<br />
cd /opt/webwork/webwork2<br />
cvs -q update -dP -r rel-2-4-dev<br />
cd /opt/webwork/pg<br />
cvs -q update -dP -r rel-2-4-dev<br />
<br />
'''''Latest development code:'''''<br />
<br />
cd /opt/webwork/webwork2<br />
cvs -q update -dPA<br />
cd /opt/webwork/pg<br />
cvs -q update -dPA<br />
<br />
=== Installing from a tarball ===<br />
<br />
Tarballs of WeBWorK releases are available from our [http://sf.net/project/showfiles.php?group_id=93112 SourceForge file release] page. You will need to download both a <code>webwork</code> tarball and a <code>pg</code> tarball. Make sure that the versions of the tarballs match. You can choose either a GZip or BZip2 archive.<br />
<br />
After downloading the tarballs, untar them somewhere (like your home directory):<br />
<br />
$ tar -xjf webwork-2.4.1.tar.bz2<br />
$ tar -xjf pg-2.4.0.tar.bz2<br />
<br />
If you have an existing WeBWorK installation, move your existing <code>webwork2</code> and <code>pg</code> directories to <code>webwork2.OLD</code> and <code>pg.OLD</code>, respectively. (You will move your existing courses and configuration over to the new directories later.)<br />
<br />
Then, become root and move the directories to the your installation directory. The installation directory should '''not''' be web-accessible. I prefer <code>/opt/webwork</code>:<br />
<br />
# cp -r webwork-2.4.1 /opt/webwork/webwork2<br />
# cp -r pg-2.4.0 /opt/webwork/pg<br />
<br />
From now on, we will assume that WeBWorK 2 is installed in <code>/opt/webwork/webwork2</code> and PG is installed in <code>/opt/webwork/pg</code>.<br />
<br />
=== Installing fonts for jsMath ===<br />
<br />
jsMath is a display mode that renders math expressions using a JavaScript implementation of the TeX math layout engine. For more information about jsMath, see http://www.math.union.edu/~dpvc/jsmath/.<br />
<br />
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, but this requires a large number of individual character images in a wide range of sizes. These are distributed in <code>webwork2/htdocs/jsMath/jsMath-fonts.tar.gz</code>, and you need to unpack this tarball before jsMath will work properly. Use the command<br />
<br />
$ cd /opt/webwork/webwork2/htdocs/jsMath<br />
$ tar -xzvf jsMath-fonts.tar.gz<br />
<br />
This will unpack the archive. Since there are 20,000 tiny files, it can take a long time, 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, and most students will have results as good as they would with the TeX fonts installed.<br />
<br />
If you do not wish to install the jsMath image fonts (to save space, for example), you should change the value of <code>noImageFonts</code> in the <code>$pg{displayModeOptions}{jsMath}</code> hash in <code>global.conf</code> to 1. This will prevent jsMath from using the image fallback methods.<br />
<br />
See also: [[#jsMath_settings|jsMath settings]]<br />
<br />
=== Creating the courses directory ===<br />
<br />
The courses directory should be located at <code>/opt/webwork/courses</code>. Placing the courses directory outside the <code>webwork2</code> directory makes updates easier.<br />
<br />
You can create your courses directory from the <code>courses.dist</code> directory distributed with WeBWorK. This directory contains the skeleton of a course called <code>modelCourse</code>, which contains the template files for three demo sets. You can opt to copy templates from this set when creating new courses.<br />
<br />
$ cd /opt/webwork/webwork2<br />
$ cp -RPp courses.dist ../courses<br />
<br />
If you prefer not to use <code>modelCourse</code>, you can create an empty courses directory instead:<br />
<br />
$ cd /opt/webwork<br />
$ mkdir courses<br />
<br />
If you are upgrading from WeBWorK 2.2.x, move your existing courses into the new <code>/opt/webwork/courses</code> directory.<br />
<br />
=== Making copies of distribution configuration files ===<br />
<br />
Some files are distributed with the <code>.dist</code> suffix. You must make copies lacking the <code>.dist</code> suffix for WeBWorK to be able to find them. This is done to ease updating with CVS. The <code>.dist</code> files may be updated during a CVS update, but your local versions will be left untouched.<br />
<br />
Before configuring the system, you must make local copies of the <code>global.conf</code> and <code>database.conf</code> configuration files, located in <code>/opt/webwork/webwork2/conf/</code>:<br />
<br />
$ cd /opt/webwork/webwork2/conf<br />
$ cp global.conf.dist global.conf<br />
$ cp database.conf.dist database.conf<br />
<br />
=== Setting permissions ===<br />
<br />
The PG installation directory and files should be owned by root and not writable by other users:<br />
<br />
# cd /opt/webwork/pg<br />
# chown -R root:root .<br />
# chmod -R u+rwX,go+rX .<br />
<br />
Most WeBWorK directories and files should also be owned by root and not writable by other users:<br />
<br />
# cd /opt/webwork/webwork2<br />
# chown -R root:root .<br />
# chmod -R u+rwX,go+rX .<br />
<br />
Certain data directories need to be writable by the web server. These are <code>DATA</code>, <code>courses</code>, <code>htdocs/tmp</code>, <code>logs</code>, and <code>tmp</code>. It is convenient to give WeBWorK administrators access to these directories as well, so they can perform administrative tasks such as removing temporary files, creating and editing courses from the command line, managing logs, and so on.<br />
<br />
The simplest way to set this up assumes that all WeBWorK administrators have root access. In this case, directories that must be writable by the web server should be given the ''group'' of the web server. In the following examples, it is assumed that the web server's group is <code>www-data</code>.<br />
<br />
If you wish to perform administrative tasks without becoming root, you can either add the WeBWorK administrators to the web server's group, or create a new group called <code>wwdata</code>, containing both the WeBWorK administrators and the web server.<br />
<br />
If you chose not to create the <code>wwdata</code> group, the WeBWorK data directories should have the group of the web server:<br />
<br />
# cd /opt/webwork/webwork2<br />
# chgrp -R www-data DATA ../courses htdocs/tmp logs tmp<br />
# chmod -R g+w DATA ../courses htdocs/tmp logs tmp<br />
# find DATA/ ../courses/ htdocs/tmp/ logs/ tmp/ -type d -a ! -name CVS -exec chmod g+s {} \;<br />
<br />
If you chose to create the <code>wwdata</code> group, the WeBWorK directories that must be writable by the web server should have that group:<br />
<br />
# cd /opt/webwork/webwork2<br />
# chgrp -R wwdata DATA ../courses htdocs/tmp logs tmp<br />
# chmod -R g+w DATA ../courses htdocs/tmp logs tmp<br />
# find DATA/ ../courses/ htdocs/tmp/ logs/ tmp/ -type d -a ! -name CVS -exec chmod g+s {} \;<br />
<br />
==== CVS updates and permissions ====<br />
<br />
In the instructions above, you set most WeBWorK and PG files to be owned and only writable by root. If you are planning to do in-place updates of the system with CVS, you may want to set those files to be owned by a regular user instead. That will let you avoid running CVS as root, which could be a security risk. One option is to create a user account that cannot be logged into directly and use it only for WeBWorK files.<br />
<br />
== Configuring your shell ==<br />
<br />
To make working with WeBWorK easier, there are a couple of changes you can make to your shell environment.<br />
<br />
Add the WeBWorK <code>bin</code> directory to your path. This will allow you to run WeBWorK command-line utilities without typing the full path to the utility. If you installed WeBWorK in the default location of <code>/opt/webwork/webwork2</code>, add the directory <code>/opt/webwork/webwork2/bin</code> to your path.<br />
<br />
{| border="1"<br />
|-<br />
| '''if your shell is''' || '''put this line''' || '''in this file''' <br />
|-<br />
| <code>bash</code> || <tt>export PATH=$PATH:/opt/webwork/webwork2/bin</tt> || <code>~/.bashrc</code> <br />
|-<br />
| <code>tcsh</code> || <tt>setenv PATH $PATH:/opt/webwork/webwork2/bin</tt> || <code>~/.cshrc</code> <br />
<br />
|}<br />
<br />
Set the <code>WEBWORK_ROOT</code> environment variable. Some command-line scripts rely on this variable to find other WeBWorK files.<br />
<br />
{| border="1"<br />
|-<br />
| '''if your shell is''' || '''put this line''' || '''in this file''' <br />
|-<br />
| <code>bash</code> || <tt>export WEBWORK_ROOT=/opt/webwork/webwork2</tt> || <code>~/.bashrc</code> <br />
|-<br />
| <code>tcsh</code> || <tt>setenv WEBWORK_ROOT /opt/webwork/webwork2</tt> || <code>~/.cshrc</code> <br />
<br />
|}<br />
<br />
== Configuring WeBWorK ==<br />
<br />
Most WW configuration is done in the file <code>/opt/webwork/webwork2/conf/global.conf</code>. This file provides system-wide configuration settings, and defaults for course settings. Any setting in this file can be overridden in the <code>course.conf</code> file for a particular course.<br />
<br />
There are several options that must be set for WW to work with your system. The rest of the file consists of customization options.<br />
<br />
=== Seed variables ===<br />
<br />
These are the main configuration variables of WeBWorK. The are used by the Apache configuration and by the system itself. Many other settings rely on these variables:<br />
<br />
{| border="1"<br />
|-<br />
| '''variable''' || '''description''' <br />
|-<br />
| <code>$webwork_url</code> || The URL associated with the WeBWorK handler. Usually <code>/webwork2</code>. <br />
|-<br />
| <code>$pg_root</code> || The path to the PG directory. Usually <code>/opt/webwork/pg</code>. <br />
|-<br />
| <code>$webwork_htdocs_url</code> || The URL of static WeBWorK hypertext files. Usually <code>/webwork2_files</code>. <br />
|-<br />
| <code>$webwork_htdocs_dir</code> || The path to the static WeBWorK hypertext files. Usually <code>$webwork_dir/htdocs</code>. <br />
|-<br />
| <code>$webwork_courses_url</code> || The URL of the courses directory. Usually <code>/webwork2_course_files</code>. <br />
|-<br />
| <code>$webwork_courses_dir</code> || The path to the courses directory. Usually <code>$webwork_dir/courses</code>. <br />
<br />
|}<br />
<br />
=== Paths to external programs ===<br />
<br />
To avoid executing malicious code, WW calls external programs using full path names.<br />
<br />
{| border="1"<br />
|-<br />
| '''variable''' || '''description''' <br />
|-<br />
| <code>$externalPrograms{mkdir}</code> || Path to <code>mkdir</code> binary. Usually <code>/bin/mkdir</code>. <br />
|-<br />
| <code>$externalPrograms{mysql}</code> || Path to <code>mysql</code> binary. Usually <code>/usr/bin/mysql</code> or <code>/usr/local/bin/mysql</code>. <br />
|-<br />
| <code>$externalPrograms{tar}</code> || Path to <code>tar</code> binary. Usually <code>/usr/bin/tar</code>. <br />
|-<br />
| <code>$externalPrograms{latex}</code> || Path to <code>latex</code> binary. Usually <code>/usr/bin/latex</code> or <code>/usr/local/bin/latex</code>. <br />
|-<br />
| <code>$externalPrograms{pdflatex}</code> || Path to <code>pdflatex</code> binary. Usually <code>/usr/bin/pdflatex</code> or <code>/usr/local/bin/pdflatex</code>. <br />
|-<br />
| <code>$externalPrograms{dvipng}</code> || Path to <code>dvipng</code> binary. Usually <code>/usr/bin/dvipng</code> or <code>/usr/local/bin/dvipng</code>. <br />
|-<br />
| <code>$externalPrograms{tth}</code> || Path to <code>tth</code> binary. Usually <code>/usr/bin/tth</code> or <code>/usr/local/bin/tth</code>. <br />
|-<br />
| <code>$externalPrograms{giftopnm}</code> || Path to <code>giftopnm</code> binary. Usually <code>/usr/bin/giftopnm</code> or <code>/usr/local/bin/giftopnm</code>. <br />
|-<br />
| <code>$externalPrograms{ppmtopgm}</code> || Path to <code>ppmtopgm</code> binary. Usually <code>/usr/bin/ppmtopgm</code> or <code>/usr/local/bin/ppmtopgm</code>. <br />
|-<br />
| <code>$externalPrograms{pnmtops}</code> || Path to <code>pnmtops</code> binary. Usually <code>/usr/bin/pnmtops</code> or <code>/usr/local/bin/pnmtops</code>. <br />
|-<br />
| <code>$externalPrograms{pnmtopng}</code> || Path to <code>pnmtopng</code> binary. Usually <code>/usr/bin/pnmtopng</code> or <code>/usr/local/bin/pnmtopng</code>. <br />
|-<br />
| <code>$externalPrograms{pngtopnm}</code> || Path to <code>pngtopnm</code> binary. Usually <code>/usr/bin/pngtopnm</code> or <code>/usr/local/bin/pngtopnm</code>. <br />
<br />
|}<br />
<br />
=== Mail settings ===<br />
<br />
WW sends mail in three instances. The PG system sends mail to report answers to questionnaires and free-response problems. The mail merge module is used to send mail to course participants, i.e. to report scores. The feedback module allows participants to send mail to course instructors.<br />
<br />
To send mail, WW needs the address of an SMTP server. When connecting to the SMTP server, it must also send an email address representing the sender of the email.<br />
<br />
{| border="1"<br />
|-<br />
| '''variable''' || '''description''' <br />
|-<br />
| <code>$mail{smtpServer}</code> || The address of an SMTP server. If the local machine is running an SMTP server (as is likely), use <code>localhost</code>. <br />
|-<br />
| <code>$mail{smtpSender}</code> || The address to send when connecting to the SMTP server. This has nothing to do with the <code>From</code> address on the mail message. <br />
<br />
|}<br />
<br />
=== Database settings ===<br />
<br />
The following settings are used in connecting to the MySQL database.<br />
<br />
{| border="1"<br />
|-<br />
| '''variable''' || '''description''' <br />
|-<br />
| <code>$database_dsn</code> || The location of the WeBWorK database. Usually <code>dbi.mysql.webwork</code>. See the Perl DBI documentation for more information about DSNs. <br />
|-<br />
| <code>$database_username</code> || The username to use when connecting to the database. Usually <code>webworkWrite</code>. <br />
|-<br />
| <code>$database_password</code> || The password to use when connecting to the database. Use a secure, random password of sufficient length. <br />
<br />
|}<br />
<br />
The <code>$dbLayoutName</code> variable controls the default database layout that will be used for new courses. If you plan to use MoodleIntegration on all new courses, set this to "sql_moodle". Otherwise, leave it set to the default, "sql_single".<br />
<br />
You can override the default when creating a new course.<br />
<br />
=== Timezone setting ===<br />
<br />
You can set the local timezone to use when displaying times using the <code>$siteDefaults{timezone}</code> setting. To get a list of timezone names, run:<br />
<br />
$ perl -MDateTime::TimeZone -e 'print join "\n", DateTime::TimeZone::all_names'<br />
<br />
To get a list of valid timezone "links" (deprecated names), run:<br />
<br />
$ perl -MDateTime::TimeZone -e 'print join "\n", DateTime::TimeZone::links'<br />
<br />
Links can be shorter and more familiar, but they may be ambiguous.<br />
<br />
=== Display modes ===<br />
<br />
WeBWorK has several techniques for displaying homework problems. Which of these modes is available is controlled by the <code>$pg{displayModes}</code> list. To disable a display mode, comment out its line from the list by inserting a <code>#</code> character at the beginning of the line.<br />
<br />
The supported display modes are as follows:<br />
<br />
{| border="1"<br />
|-<br />
| '''display mode''' || '''status''' || '''description''' <br />
|-<br />
| <code>plainText</code> || STABLE || This mode shows the raw TeX source of mathematics. It is useful for debugging. <br />
|-<br />
| <code>formattedText</code> || DEPRECATED || This mode uses the <code>tth</code> program to represent mathematics as HTML table structures. Output quality depends on the browser. There are typically font problems on the Mac platform. <br />
|-<br />
| <code>images</code> || STABLE || This mode uses the <code>dvipng</code> program to represent mathematics as PNG images. This gives excellent output on all browsers, but uses more bandwidth, as the images must be sent to the client. <br />
|-<br />
| <code>jsMath</code> || STABLE || This mode uses jsMath to display mathematics. The raw TeX is sent to the client, where a JavaScript program displays it. This requires the client to have a decent JavaScript implementation, and can be slow on older machines. <br />
|-<br />
| <code>asciimath</code> || DEPRECATED || This mode converts mathematics to ASCIIMath on the server and uses a <nobpo>JavaScript to convert them to MathML on the client. Requires a Mozilla-based browser or MSIE with the MathPlater plugin. <br />
|-<br />
| <code>LaTeXMathML</code> || EXPERIMENTAL || This mode is a modification of the <code>asciimath</code> mode that skips the intermediate ASCIIMath form. Requires a Mozilla-based browser or MSIE with the MathPlater plugin. <br />
<br />
|}<br />
<br />
=== jsMath settings ===<br />
<br />
When a student doesn't have the TeX fonts installed, jsMath can display a warning message pointing to the jsMath font download site. Since the image-mode fallback method is of high enough quality, most students will not feel the need to download and install the fonts, so this warning message is disabled by default. (It tended to worry the students, and there is a link to the download page on the control panel that is new in version 2.0 of jsMath).<br />
<br />
jsMath settings are stored in the <code>$pg{displayModeOptions}{jsMath}</code> hash:<br />
<br />
{| border="1"<br />
|-<br />
| '''variable''' || '''description''' <br />
|-<br />
| <code>reportMissingFonts</code> || Set to 1 if you want to have a message displayed for students who don't have the TeX fonts installed. The warning will only be shown on the first page they view that used jsMath (and there is a "hide" button that they can use to hide it even on that page). They can use the control panel to disable the warning messages permanently for their computer, if they want, so even if you turn on the warning message, it is not too intrusive. <br />
|-<br />
| <code>missingFontMessage</code> || An HTML string that will be used for the missing font message (when <code>reportMissingFonts</code> is non-zero). This string will replace the default warning message, and can be used to point to your own page of instructions for getting the fonts, for example, or for using the control panel to disable the warning. <br />
|-<br />
| <code>noImageFonts</code> || Set to 1 to prevent jsMath from using the image fallback method. This can be useful if you elected not to unpack the <code>jsMath-fonts.tar.gz</code> archive. <br />
|-<br />
| <code>processDoubleClicks</code> || By default, double-clicking on the math expression will display the TeX source that generated it. If you wish to disable this behavior, set this to 0. (Note that the raw TeX is still available in the page's HTML source.) <br />
<br />
|}<br />
<br />
== Configuring the database ==<br />
<br />
WeBWorK uses a single MySQL database to store course data. By default, this database is named <code>webwork</code> and is accessed by a MySQL user named <code>webworkWrite</code>.<br />
<br />
=== Creating a new database ===<br />
<br />
If this is a new installation, you must create the <code>webwork</code> database:<br />
<br />
$ mysql -u root -p mysql<br />
Password: '''***'''<br />
> CREATE DATABASE webwork;<br />
> GRANT SELECT, INSERT, UPDATE, DELETE, CREATE, ALTER, DROP, LOCK TABLES<br />
ON webwork.* TO webworkWrite@localhost IDENTIFIED BY 'password';<br />
> exit<br />
Bye<br />
$ <br />
<br />
(Replace <code>password</code> with the password you set for <code>$database_password</code> in <code>global.conf</code>.)<br />
<br />
=== Using an existing database ===<br />
<br />
If you already have a <code>webwork</code> database from WeBWorK 2.1.x or 2.2.x, you must run the utility <code>wwdb_check</code> to make sure that it is up-to-date for use with 2.4.x. You should '''not''' use this utility if you are upgrading from 2.3.x or an earlier version of 2.4.x. (For example, from 2.4.1 to 2.4.2.)<br />
<br />
To run the utility:<br />
<br />
$ /opt/webwork/webwork2/bin/wwdb_check<br />
<br />
The script will look at the structure of your <code>webwork</code> database, and alert you to missing tables, missing fields, and incorrect field types. You will have the option to fix these problems.<br />
<br />
WeBWorK 2.4 requires permision to <code>LOCK TABLES</code> in the <code>webwork</code> database. Use the <code>mysql</code> console to add it:<br />
<br />
$ mysql -u root mysql<br />
Password: '''***'''<br />
> GRANT LOCK TABLES ON webwork.* TO webworkWrite@localhost;<br />
> exit;<br />
$<br />
<br />
=== Automated database initialization and upgrade ===<br />
<br />
WeBWorK 2.3.0 introduces an automatic database upgrade system. Rather than manually issuing SQL commands to make changes to the database, or using ad-hoc scripts like <code>wwdb_addgw</code>, there is a single script called <code>wwdb_upgrade</code> that applies any necessary updates. It should be run when creating a new database, and any time you upgrade WeBWorK.<br />
<br />
$ /opt/webwork/webwork2/bin/wwdb_upgrade<br />
<br />
Add the <code>-v</code> switch to get more information about what the script is doing.<br />
<br />
=== Image depths database ===<br />
<br />
The "images" display mode has the capability to store depth information in a <code>depths</code> table when equation images are generated. The information allows better alignment of images with surrounding text. In previous versions of WeBWorK, the <code>depths</code> table was stored in a separate database, named <code>DvipngDepths</code>. Starting with WeBWorK 2.3.0, it is stored in the <code>webwork</code> database itself.<br />
<br />
If you are upgrading an existing installation, and you had set <code>$pg{displayModeOptions}{images}{dvipng_align}</code> to <code>mysql</code> in the old version, you have depths information stranded in your old <code>DvipngDepths</code> database, and existing images will lose access to this information.<br />
<br />
The easiest way to solve this is to delete the existing images. This is probably a good idea anyway when upgrading since existing images won't take advantage of rendering improvements, dvipng improvements, etc. To delete the images:<br />
<br />
$ /opt/webwork/webwork2/bin/remove_stale_images --days=0 --delete<br />
<br />
== Configuring Apache ==<br />
<br />
=== Testing mod_perl ===<br />
<br />
To verify that mod_perl is installed, you can use mod_info to list the installed modules. If mod_info itself is disabled or not installed, you can either install/enable it, or skip this test and check using Apache::Status instead. The process for installing and enabling modules varies by distribution. To configure mod_perl, uncomment the location block <code>&lt;Location /server-info&gt;</code> in your Apache config file (usually <code>httpd.conf</code> or <code>apache.conf</code>). It should look something like this:<br />
<br />
<Location /server-info><br />
SetHandler server-info<br />
Order deny,allow<br />
Deny from all<br />
Allow from localhost<br />
Allow from .yourschool.edu<br />
</Location><br />
<br />
You may have to add the <code>Order</code>, <code>Deny</code>, and <code>Allow</code> lines yourself, or there may already be lines there you can customize. Restart Apache (<code>apachectl graceful</code>) and visit <code>http://yourserver.yourschool.edu/server-info</code>. You should see an entry in the list of active modules for mod_perl.<br />
<br />
To further test mod_perl, you can install the Perl module Apache::Status. After installing, add the following section to your Apache config file:<br />
<br />
<Location /perl-status><br />
SetHandler perl-script<br />
PerlHandler Apache::Status<br />
Order deny,allow<br />
Deny from all<br />
Allow from localhost<br />
Allow from .yourschool.edu<br />
</Location><br />
<br />
Restart Apache (<code>apachectl graceful</code>) and visit <code>http://yourserver.yourschool.edu/perl-status</code>. You should see a page listing various information about mod_perl.<br />
<br />
=== Enabling WeBWorK ===<br />
<br />
Once mod_perl is working, Apache must be configured to handle requests for WeBWorK. Apache provides access to WeBWorK through three URL locations:<br />
<br />
* The location that is handled by the <code>Apache::WeBWorK</code> module, usually <code>/webwork2</code>.<br />
* The location of system-wide resources, usually <code>/webwork2_files</code>.<br />
* The location of course-specific resources, usually <code>/webwork2_course_files</code>.<br />
<br />
WeBWorK ships with an Apache config file that you can include in your main Apache config file. The file is named <code>webwork.apache-config.dist</code> and located in the <code>conf</code> directory. First, copy the file to <code>webwork.apache-config</code>:<br />
<br />
$ cd /opt/webwork/webwork2/conf<br />
$ cp webwork.apache-config.dist webwork.apache-config<br />
<br />
Then, edit the copy to set the <code>$webwork_dir</code> variable to the path of the directory containing the WeBWorK installation. This is usually <code>/opt/webwork/webwork2</code>. This value is used to read the WeBWorK configuration file and get the rest of the configuration data.<br />
<br />
Further down in the file, you may want to customize the directives used to define the association between Apache and WeBWorK. Specifically, you may need to add the following to the <code>&lt;Location&gt;</code> and <code>&lt;Directory&gt;</code> stanzas, to permit access:<br />
<br />
Order allow,deny<br />
Allow from all<br />
<br />
After editing <code>webwork.apache-config</code>, append the following line to your Apache configuration file:<br />
<br />
Include /opt/webwork/webwork2/conf/webwork.apache-config<br />
<br />
If you are upgrading from a previous version of WeBWorK which did not use the <code>webwork.apache-config</code> file, you will need to remove the WeBWorK-related directives from your Apache configuration.<br />
<br />
Then restart Apache and test your configuration:<br />
<br />
* Test the <code>/webwork2</code> location by visiting <code>http://yourserver.yourschool.edu/webwork2</code>. You should see the WeBWorK home page, with no courses listed.<br />
* Test the <code>/webwork2_files</code> location by visiting <code>http://yourserver.yourschool.edu/webwork2_files</code>. You should see the "WeBWorK Placeholder Page".<br />
* You cannot test the <code>/webwork2_course_files</code> location until you have created a course.<br />
<br />
=== Experimental support for Apache 2.0.x ===<br />
<br />
If you are using Apache 2.0.x, follow the directions above, with these changes:<br />
<br />
Enable the libapreq module by adding the following line to your Apache2 configuration file. Place this line with the other <code>LoadModule</code> lines.<br />
<br />
LoadModule apreq_module modules/mod_apreq.so<br />
<br />
Use the module Apache2::Status in place of Apache::Status.<br />
<br />
Use the file <code>webwork.apache2-config</code> in place of <code>webwork.apache-config</code>.<br />
<br />
== Creating the admin course ==<br />
<br />
WeBWorK includes web-based course management tools. Access to these tools is controlled by a special course named <code>admin</code>. The instructors in this course are permittied to perform administrative functions. If the admin course exists, a '''Course Administration''' link will appear on the WeBWorK home page.<br />
<br />
If you created a <code>wwadmin</code> group, create the admin course as follows:<br />
<br />
$ cd /opt/webwork/courses<br />
$ newgrp wwadmin<br />
$ umask 2<br />
$ addcourse<br />
$ addcourse admin --db-layout=sql_single --users=adminClasslist.lst --professors=admin<br />
$ exit<br />
<br />
If you did not create a <code>wwadmin</code> group, create the admin course as follows:<br />
<br />
$ sudo -u www-data addcourse admin --db-layout=sql_single --users=adminClasslist.lst --professors=admin<br />
<br />
Replace <code>www-data</code> with the user your webserver runs as.<br />
<br />
See CourseAdministrationManual#Permissions_issues for more about getting the permission right when using the command-line tools.<br />
<br />
After you create the course, visit the WeBWorK home page on your server, usually located at <code>http://yourserver.yourschool.edu/webwork2</code>. Click on the '''Course Administration''' link. You can also access the admin course directly, at <code>http://yourserver.yourschool.edu/webwork2/admin</code>.<br />
<br />
To log in, enter <code>admin</code> for your username and <code>admin</code> for your password. Once logged into the admin course, the first thing you should do is change the password for the admin account. You can do this by clicking the '''Password/Email''' link on the links menu. After you do this, you may add accounts for any additional people who should have administrative access using the '''Class List Editor''' link. <br />
<br />
== Where to go from here ==<br />
<br />
Read [[Course Administration]] for more information about managing courses.<br />
<br />
Read [[Problem Libraries]] for information on installing libraries of pre-written WeBWorK problems.<br />
<br />
Read [[Moodle Integration]] for information on including WeBWorK problem sets in Moodle courses. (Experimental)<br />
<br />
Read [[LDAP Authentication]] for information about LDAP authentication. (Experimental)<br />
<br />
Consult [[:Category:Administrators]] for other WeBWorK documentation for system administrators.<br />
<br />
[[Category:Installation Manuals]]</div>Xiong Chiamiovhttps://webwork.maa.org/mediawiki_new/index.php?title=Installation_Manual_for_2.4&diff=1351Installation Manual for 2.42008-07-03T19:28:09Z<p>Xiong Chiamiov: /* Experimental support for Apache 2.0.x */ hte -> the</p>
<hr />
<div>== Installation instructions for specific operating systems ==<br />
<br />
These manuals offer command-by-command procedures (and fewer choices) than the general instructions. They are targeted at UNIX beginners.<br />
<br />
* [[Installation Manual for 2.4 on Ubuntu 8.04]]<br />
* [[Installation Manual for 2.4 on Fedora 9]]<br />
<br />
[[:Category:Installation_Manuals|More installation manuals...]]<br />
<br />
== Dependencies ==<br />
<br />
=== Apache ===<br />
<br />
WeBWorK supports Apache 1.3 and 2.0. Apache 2.2 is supported experimentally. WeBWorK requires that the <code>mod_alias</code> module be available. Most vendors compile their Apache packages with the necessary features enabled.<br />
<br />
==== Apache 1.3 ====<br />
<br />
* Source: http://httpd.apache.org/<br />
* Debian/Ubuntu: <code>apache</code> <br />
* Red Hat/Fedora: build from source<br />
<br />
==== Apache 2.0 or 2.2 ====<br />
<br />
Apache must be using the <code>prefork</code> MPM. This is because the <code>Safe</code> module, which WeBWorK makes extensive use of, is not threadsafe. This is set at compile time with the <code>--with-mpm=prefork</code> switch to the <code>configure</code> script.<br />
<br />
* Source: http://httpd.apache.org/<br />
* Debian/Ubuntu: <code>apache2</code> with <code>apache2-mpm-prefork</code><br />
* Red Hat/Fedora: build from source; or see below<br />
<br />
''On my Scientific Linux 4 box (i.e., RHEL4) there is no need to recompile apache; mpm-prefork is already set. Of course mod_perl2 must be compiled!'' -- Niels Walet - 13 Mar 2007<br />
<br />
=== Perl ===<br />
<br />
WeBWorK requires Perl 5.6.1 or higher.<br />
<br />
* Source: http://perl.org/<br />
* Debian/Ubuntu: <code>perl</code> (in the default install)<br />
* Red Hat/Fedora: <code>perl</code> (in the default install)<br />
<br />
=== Perl modules ===<br />
<br />
The following Perl modules are required. All are available from [http://cpan.org/ CPAN], and many vendors provide packages of these modules. To see if a module is installed on your system, use the following command. Replace <code>Module</code> with the name of the module.<br />
<br />
$ perl -MModule -e 'print "installed!\n"'<br />
<br />
To check that all modules used by WeBWorK are installed you should run the script:<br />
webwork2/bin/check_modules.pl [apache1|apache2] <br />
or<br />
perl webwork2/bin/check_modules.pl [apache1|apache2]<br />
which checks for the modules needed for either an apache1 or apache2 installation of WeBWorK respectively.<br />
<br />
To install a missing module from CPAN, use the following command as root. Replace <code>Module</code> with the name of the module.<br />
<br />
# perl -MCPAN -e "install Module"<br />
<br />
For more information about using CPAN, consult the [http://cpan.org/misc/cpan-faq.html CPAN FAQ].<br />
<br />
{| border="1"<br />
|-<br />
| '''module'''<br />
| '''Debian/Ubuntu package'''<br />
| '''Gentoo package'''<br />
| '''Fedora Core 7 package'''<br />
|-<br />
| Apache::Request<br/><small>(only if using Apache 1.3.x)<br />
| <code>libapache-request-perl</code><br />
| <br />
| <br />
|-<br />
| Apache2::Request<br/><small>(only if using Apache 2.0.x)<br />
| <code>libapache2-request-perl</code><br />
| <code>libapreq</code><br />
| <code>perl-libapreq2</code><br />
|-<br />
| Data::UUID<br />
| <code>libdata-uuid-perl</code> <br><small>(virtual package, provided by <code>libossp-uuid-perl</code>)</small><br />
| <code>Data-UUID</code><br />
| <code>perl-uuid</code><br />
|-<br />
| Date::Format<br />
| <code>libtimedate-perl</code><br />
| <code>TimeDate</code><br />
| <code>perl-TimeDate</code><br />
|-<br />
| Date::Parse<br />
| <code>libtimedate-perl</code><br />
| <code>TimeDate</code><br />
| <code>perl-TimeDate</code><br />
|-<br />
| DateTime<br />
| <code>libdatetime-perl</code><br />
| <code>DateTime</code><br />
| <code>perl-DateTime</code><br />
|-<br />
| DBD::mysql<br />
| <code>libdbd-mysql-perl</code><br />
| <code>DBD-mysql</code><br />
| <code>perl-DBD-MySQL</code><br />
|-<br />
| Email::Address<br />
| <code>libemail-address-perl</code><br />
| <code>Email-Address</code><br />
| <code>perl-Email-Address</code><br />
|-<br />
| GD<br />
| <code>libgd-gd2-perl</code><br />
| <code>GD</code><br />
| <code>perl-GD</code><br />
|-<br />
| Iterator<br />
| not packaged<br />
| not packaged<br />
| not packaged<br />
|-<br />
| Iterator::Util<br />
| not packaged<br />
| not packaged<br />
| not packaged<br />
|-<br />
| Mail::Sender<br />
| <code>libmail-sender-perl</code><br />
| <code>Mail-Sender</code><br />
| <code>perl-Mail-Sender</code><br />
|-<br />
| SQL::Abstract<br />
| <code>libsql-abstract-perl</code><br />
| unknown<br />
| <code>perl-SQL-Abstract</code> <br />
|-<br />
| String::ShellQuote<br />
| <code>libstring-shellquote-perl</code><br />
| <code>String-ShellQuote</code><br />
| <code>perl-String-ShellQuote</code><br />
|-<br />
| Time::HiRes<br><small>(included in Perl 5.8 and higher)</small><br />
| included in <code>perl</code> package<br />
| unknown<br />
| included in <code>perl</code> package <br />
|-<br />
| XML::Parser<br />
| <code>libxml-parser-perl</code><br />
| <code>libxml-perl</code><br />
| <code>perl-XML-Parser</code> <br />
|-<br />
| XML::Parser::EasyTree<br />
| not packaged<br />
| unknown<br />
| not packaged <br />
|-<br />
| XML::Writer<br />
| <code>libxml-writer-perl</code><br />
| <code>XML-Writer</code><br />
| <code>perl-XML-Writer</code> <br />
|}<br />
<br />
==== DateTime::TimeZone: use version 0.34 or later ====<br />
<br />
Versions of DateTime::TimeZone (a component of DateTime) below 0.34 suffer from a problem with displaying some time zones. Make sure you have version 0.34 or later.<br />
<br />
==== Problems building Time::HiRes ====<br />
<br />
Some users have reported problems building Time::HiRes through CPAN. If this is your experience, try downloading the Time::HiRes tarball from http://search.cpan.org/~jhi/Time-HiRes/ and building it manually (<code>perl Makefile.PL && make && make test && make install</code>).<br />
<br />
==== Problems building Apache::Request or Apache2::Request ====<br />
<br />
Apache::Request is one component of the libapreq library. If you run into problems building it through CPAN, try downloading the libapreq tarball from http://httpd.apache.org/apreq/.<br />
<br />
Apache 2.0.x users should use libapreq2.<br />
<br />
=== mod_perl ===<br />
<br />
WeBWorK uses mod_perl to interface with the Apache server. If compiling mod_perl from source, use the <code>EVERYTHING=1</code> flag to enable all mod_perl features. Most vendors compile their mod_perl packages with this setting enabled.<br />
<br />
==== Apache 1.3 ====<br />
<br />
* Source: http://perl.apache.org/download/<br />
* Debian/Ubuntu: <code>libapache-mod-perl</code> <br />
* Red Hat/Fedora: build from source; see below.<br />
* Gentoo: <code>mod_perl </code><br />
<br />
==== Apache 2.0 ====<br />
<br />
* Source: http://perl.apache.org/download/ <br />
* Debian/Ubuntu: <code>libapache2-mod-perl</code> <br />
* Red Hat/Fedora: build from source <br />
<br />
==== RHEL4/Fedora build notes ====<br />
<br />
''I had to use the flags below to get the compile to work correctly:''<br />
<br />
perl Makefile.PL EVERYTHING=1 DO_HTTPD=1 USE_APACI=1 APACHE_PREFIX=/usr/local/apache<br />
<br />
-- Main.MarkHamrick<br />
<br />
=== MySQL ===<br />
<br />
MySQL 4.0.x or later is required. If you are going to be using the experimental Moodle Integration, MySQL 4.1.x or later is required.<br />
<br />
* Source: http://dev.mysql.com/downloads/ <br />
* Debian/Ubuntu: 4.0.x: <code>mysql-server</code>; 4.1.x: <code>mysql-server-4.1</code><br />
* RHEL4/Fedora: <code>mysql-sever</code>, <code>mysql-client</code> <br />
* Gentoo: <code>mysql </code><br />
<br />
=== LaTeX ===<br />
<br />
WeBWorK requires LaTeX for generating hardcopy output and displaying mathematics graphically. Any standard LaTeX distribution that provides the commands <code>latex</code> and <code>pdflatex</code> should work. We use TeTeX.<br />
<br />
* Source: http://tug.org/tetex/ <br />
* Debian/Ubuntu: <code>tetex-bin</code>, <code>tetex-extra</code> <br />
* Red Hat/Fedora: <code>tetex</code>, <code>tetex-latex</code> <br />
* Gentoo: <code>tetex</code><br />
<br />
=== Netpbm ===<br />
<br />
WeBWorK requires Netpbm to convert images among the GIF, PNG, and EPS formats.<br />
<br />
* Source: http://netpbm.sf.net/ <br />
* Debian/Ubuntu: <code>netpbm</code> <br />
* Red Hat/Fedora: build from source <br />
* Gentoo: <code>netpbm </code><br />
<br />
=== dvipng ===<br />
<br />
WeBWorK uses dvipng to display mathematics graphically. It is only required if you wish to use the <code>images</code> display mode. dvipng requires the <code>preview.sty</code> file from the [http://preview-latex.sf.net/ preview-latex] package.<br />
<br />
* Source: http://dvipng.sf.net/ <br />
* Debian: <code>dvipng</code>, <code>preview-latex-style</code> <br />
* Red Hat/Fedora: <code>preview-latex-common-0.9.1-1.fedora.noarch.rpm</code> <br />
* Gentoo: <code>dvipng</code> <br />
<br />
WeBWorK is initially configured to work with dvipng 1.0 or greater, but can be reconfigured to work with dvipng 0.8 or 0.9. See <code>webwork2/lib/WeBWorK/Constants.pm</code> for details.<br />
<br />
=== TtH ===<br />
<br />
WeBWorK uses TtH to display mathematics as formatted HTML. It is only required if you wish to use the <code>formatted-text</code> display mode.<br />
<br />
* Source: http://hutchinson.belmont.ma.us/tth/ <br />
* Debian:*|| <code>tth</code><br />
* Red Hat/Fedora: build from source <br />
* Gentoo: <code>tth</code><br />
<br />
== Installing the WeBWorK files ==<br />
<br />
WeBWorK is typically installed using CVS. We provide version tags that correspond to each released version of WeBWorK. This ensures that you can maintain a stable system, and experimental upgrades will not be applied to your installation.<br />
<br />
We also provide tarballs for each release. They contain the necessary CVS data to update from CVS at a later date. Choose a tarball if for some reason you do not want to use CVS. Keep in mind that because of the layout of files within the <code>webwork2</code> directory tree, upgrading an existing installation is harder using a tarball than using CVS.<br />
<br />
=== Creating the base directory directory ===<br />
<br />
Before you begin installing files, create a base directory to hold them. We prefer <code>/opt/webwork</code>:<br />
<br />
# mkdir -p /opt/webwork<br />
<br />
To make things easier during the installation, you can give yourself write permission to this directory. That way, you won't have to become root to install the WeBWorK files:<br />
<br />
# chown yourNameHere /opt/webwork<br />
<br />
=== Installing from CVS ===<br />
<br />
Installing from CVS allows you more flexibility in selecting versions of the WeBWorK code between or ahead of releases. You have several options, depending on which release tag you select when accessing the CVS repository.<br />
<br />
==== CVS tags ====<br />
<br />
'''''Released version:''''' By specifying the '''rel-2-4-1''' tag, you get the same version of the code that you would by downloading the WeBWorK 2.4.1 tarball. This is the most conservative option. Updating will have no effect -- this code will never change.<br />
<br />
'''''Released version with patches:''''' By specifying the '''rel-2-4-dev''' tag, you can stay up to date with the latest bug fixes against the released version of WeBWorK 2.4. Few, if any, new features are introduced on a patch branch. We recommend that you choose this option.<br />
<br />
'''''Latest code:''''' If you do not specify a release tag, you will get the latest code. Since this code is a work in progress, it is sometimes unstable or broken. If you require features that are not in a stable release, and are willing to devote more time to keeping your installation running smoothly, this may be the option for you.<br />
<br />
No matter what tag you chose, you can change later by specifying a new tag when running <code>cvs upgrade</code>.<br />
<br />
==== New installation from CVS ====<br />
<br />
If you do not have an existing WeBWorK installation, use the following commands to check out copies of the <code>webwork2</code> and <code>pg</code> modules. If you are prompted for a password, press enter.<br />
<br />
'''''Released version:'''''<br />
<br />
<code>$ cvs -d :pserver:anoncvs@cvs.webwork.rochester.edu:/webwork/cvs/system checkout -r rel-2-4-1 webwork2</code><br/><br />
<code>$ cvs -d :pserver:anoncvs@cvs.webwork.rochester.edu:/webwork/cvs/system checkout -r rel-2-4-0 pg</code><br />
<br />
'''''Released version with patches:'''''<br />
<br />
<code>$ cvs -d :pserver:anoncvs@cvs.webwork.rochester.edu:/webwork/cvs/system checkout -r rel-2-4-dev webwork2 pg</code><br />
<br />
'''''Latest development code:'''''<br />
<br />
<code>$ cvs -d :pserver:anoncvs@cvs.webwork.rochester.edu:/webwork/cvs/system checkout webwork2 pg</code><br />
<br />
The message <code>warning: cannot open /webwork/cvs/system/CVSROOT/val-tags read/write: Permission denied</code> is harmless and should be ignored.<br />
<br />
After checkout finishes, become root and move the directories to the your installation directory. I prefer <code>/opt/webwork</code>:<br />
<br />
# cp -r webwork2 /opt/webwork/webwork2<br />
# cp -r pg /opt/webwork/pg<br />
<br />
==== Upgrading using CVS ====<br />
<br />
If you already have an existing WeBWorK installation, use the following commands to update your exsting files to version 2.4. You may need to become root to run these commands (depending on your permissions situation).<br />
<br />
Take note of the messages that CVS gives during the update. If you have modified files, you may see the message <code>Merging differences between ''version1'' and ''version2'' into _filename_</code>. This indicates that the file in question is updated in WeBWorK 2.4, and since you also made local modifications to it, CVS is attempting to merge the two changed versions.<br />
<br />
If this process fails, because the same parts of the file were modified in both versions, you will see the message <code>rcsmerge: warning: conflicts during merge</code>. If you end up in this situation, you will need to resolve the conflict by editing the file in question. Consult this [http://ximbiot.com/cvs/manual/cvs-1.11.22/cvs_10.html#SEC85 conflicts example] from the CVS manual.<br />
<br />
The message <code>warning: cannot open /webwork/cvs/system/CVSROOT/val-tags read/write: Permission denied</code> is harmless and should be ignored.<br />
<br />
'''''Released version:'''''<br />
<br />
cd /opt/webwork/webwork2<br />
cvs -q update -dP -r rel-2-4-1<br />
cd /opt/webwork/pg<br />
cvs -q update -dP -r rel-2-4-0<br />
<br />
'''''Released version with patches:'''''<br />
<br />
cd /opt/webwork/webwork2<br />
cvs -q update -dP -r rel-2-4-dev<br />
cd /opt/webwork/pg<br />
cvs -q update -dP -r rel-2-4-dev<br />
<br />
'''''Latest development code:'''''<br />
<br />
cd /opt/webwork/webwork2<br />
cvs -q update -dPA<br />
cd /opt/webwork/pg<br />
cvs -q update -dPA<br />
<br />
=== Installing from a tarball ===<br />
<br />
Tarballs of WeBWorK releases are available from our [http://sf.net/project/showfiles.php?group_id=93112 SourceForge file release] page. You will need to download both a <code>webwork</code> tarball and a <code>pg</code> tarball. Make sure that the versions of the tarballs match. You can choose either a GZip or BZip2 archive.<br />
<br />
After downloading the tarballs, untar them somewhere (like your home directory):<br />
<br />
$ tar -xjf webwork-2.4.1.tar.bz2<br />
$ tar -xjf pg-2.4.0.tar.bz2<br />
<br />
If you have an existing WeBWorK installation, move your existing <code>webwork2</code> and <code>pg</code> directories to <code>webwork2.OLD</code> and <code>pg.OLD</code>, respectively. (You will move your existing courses and configuration over to the new directories later.)<br />
<br />
Then, become root and move the directories to the your installation directory. The installation directory should '''not''' be web-accessible. I prefer <code>/opt/webwork</code>:<br />
<br />
# cp -r webwork-2.4.1 /opt/webwork/webwork2<br />
# cp -r pg-2.4.0 /opt/webwork/pg<br />
<br />
From now on, we will assume that WeBWorK 2 is installed in <code>/opt/webwork/webwork2</code> and PG is installed in <code>/opt/webwork/pg</code>.<br />
<br />
=== Installing fonts for jsMath ===<br />
<br />
jsMath is a display mode that renders math expressions using a JavaScript implementation of the TeX math layout engine. For more information about jsMath, see http://www.math.union.edu/~dpvc/jsmath/.<br />
<br />
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, but this requires a large number of individual character images in a wide range of sizes. These are distributed in <code>webwork2/htdocs/jsMath/jsMath-fonts.tar.gz</code>, and you need to unpack this tarball before jsMath will work properly. Use the command<br />
<br />
$ cd /opt/webwork/webwork2/htdocs/jsMath<br />
$ tar -xzvf jsMath-fonts.tar.gz<br />
<br />
This will unpack the archive. Since there are 20,000 tiny files, it can take a long time, 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, and most students will have results as good as they would with the TeX fonts installed.<br />
<br />
If you do not wish to install the jsMath image fonts (to save space, for example), you should change the value of <code>noImageFonts</code> in the <code>$pg{displayModeOptions}{jsMath}</code> hash in <code>global.conf</code> to 1. This will prevent jsMath from using the image fallback methods.<br />
<br />
See also: [[#jsMath_settings|jsMath settings]]<br />
<br />
=== Creating the courses directory ===<br />
<br />
The courses directory should be located at <code>/opt/webwork/courses</code>. Placing the courses directory outside the <code>webwork2</code> directory makes updates easier.<br />
<br />
You can create your courses directory from the <code>courses.dist</code> directory distributed with WeBWorK. This directory contains the skeleton of a course called <code>modelCourse</code>, which contains the template files for three demo sets. You can opt to copy templates from this set when creating new courses.<br />
<br />
$ cd /opt/webwork/webwork2<br />
$ cp -RPp courses.dist ../courses<br />
<br />
If you prefer not to use <code>modelCourse</code>, you can create an empty courses directory instead:<br />
<br />
$ cd /opt/webwork<br />
$ mkdir courses<br />
<br />
If you are upgrading from WeBWorK 2.2.x, move your existing courses into the new <code>/opt/webwork/courses</code> directory.<br />
<br />
=== Making copies of distribution configuration files ===<br />
<br />
Some files are distributed with the <code>.dist</code> suffix. You must make copies lacking the <code>.dist</code> suffix for WeBWorK to be able to find them. This is done to ease updating with CVS. The <code>.dist</code> files may be updated during a CVS update, but your local versions will be left untouched.<br />
<br />
Before configuring the system, you must make local copies of the <code>global.conf</code> and <code>database.conf</code> configuration files, located in <code>/opt/webwork/webwork2/conf/</code>:<br />
<br />
$ cd /opt/webwork/webwork2/conf<br />
$ cp global.conf.dist global.conf<br />
$ cp database.conf.dist database.conf<br />
<br />
=== Setting permissions ===<br />
<br />
The PG installation directory and files should be owned by root and not writable by other users:<br />
<br />
# cd /opt/webwork/pg<br />
# chown -R root:root .<br />
# chmod -R u+rwX,go+rX .<br />
<br />
Most WeBWorK directories and files should also be owned by root and not writable by other users:<br />
<br />
# cd /opt/webwork/webwork2<br />
# chown -R root:root .<br />
# chmod -R u+rwX,go+rX .<br />
<br />
Certain data directories need to be writable by the web server. These are <code>DATA</code>, <code>courses</code>, <code>htdocs/tmp</code>, <code>logs</code>, and <code>tmp</code>. It is convenient to give WeBWorK administrators access to these directories as well, so they can perform administrative tasks such as removing temporary files, creating and editing courses from the command line, managing logs, and so on.<br />
<br />
The simplest way to set this up assumes that all WeBWorK administrators have root access. In this case, directories that must be writable by the web server should be given the ''group'' of the web server. In the following examples, it is assumed that the web server's group is <code>www-data</code>.<br />
<br />
If you wish to perform administrative tasks without becoming root, you can either add the WeBWorK administrators to the web server's group, or create a new group called <code>wwdata</code>, containing both the WeBWorK administrators and the web server.<br />
<br />
If you chose not to create the <code>wwdata</code> group, the WeBWorK data directories should have the group of the web server:<br />
<br />
# cd /opt/webwork/webwork2<br />
# chgrp -R www-data DATA ../courses htdocs/tmp logs tmp<br />
# chmod -R g+w DATA ../courses htdocs/tmp logs tmp<br />
# find DATA/ ../courses/ htdocs/tmp/ logs/ tmp/ -type d -a ! -name CVS -exec chmod g+s {} \;<br />
<br />
If you chose to create the <code>wwdata</code> group, the WeBWorK directories that must be writable by the web server should have that group:<br />
<br />
# cd /opt/webwork/webwork2<br />
# chgrp -R wwdata DATA ../courses htdocs/tmp logs tmp<br />
# chmod -R g+w DATA ../courses htdocs/tmp logs tmp<br />
# find DATA/ ../courses/ htdocs/tmp/ logs/ tmp/ -type d -a ! -name CVS -exec chmod g+s {} \;<br />
<br />
==== CVS updates and permissions ====<br />
<br />
In the instructions above, you set most WeBWorK and PG files to be owned and only writable by root. If you are planning to do in-place updates of the system with CVS, you may want to set those files to be owned by a regular user instead. That will let you avoid running CVS as root, which could be a security risk. One option is to create a user account that cannot be logged into directly and use it only for WeBWorK files.<br />
<br />
== Configuring your shell ==<br />
<br />
To make working with WeBWorK easier, there are a couple of changes you can make to your shell environment.<br />
<br />
Add the WeBWorK <code>bin</code> directory to your path. This will allow you to run WeBWorK command-line utilities without typing the full path to the utility. If you installed WeBWorK in the default location of <code>/opt/webwork/webwork2</code>, add the directory <code>/opt/webwork/webwork2/bin</code> to your path.<br />
<br />
{| border="1"<br />
|-<br />
| '''if your shell is''' || '''put this line''' || '''in this file''' <br />
|-<br />
| <code>bash</code> || <tt>export PATH=$PATH:/opt/webwork/webwork2/bin</tt> || <code>~/.bashrc</code> <br />
|-<br />
| <code>tcsh</code> || <tt>setenv PATH $PATH:/opt/webwork/webwork2/bin</tt> || <code>~/.cshrc</code> <br />
<br />
|}<br />
<br />
Set the <code>WEBWORK_ROOT</code> environment variable. Some command-line scripts rely on this variable to find other WeBWorK files.<br />
<br />
{| border="1"<br />
|-<br />
| '''if your shell is''' || '''put this line''' || '''in this file''' <br />
|-<br />
| <code>bash</code> || <tt>export WEBWORK_ROOT=/opt/webwork/webwork2</tt> || <code>~/.bashrc</code> <br />
|-<br />
| <code>tcsh</code> || <tt>setenv WEBWORK_ROOT /opt/webwork/webwork2</tt> || <code>~/.cshrc</code> <br />
<br />
|}<br />
<br />
== Configuring WeBWorK ==<br />
<br />
Most WW configuration is done in the file <code>/opt/webwork/webwork2/conf/global.conf</code>. This file provides system-wide configuration settings, and defaults for course settings. Any setting in this file can be overridden in the <code>course.conf</code> file for a particular course.<br />
<br />
There are several options that must be set for WW to work with your system. The rest of the file consists of customization options.<br />
<br />
=== Seed variables ===<br />
<br />
These are the main configuration variables of WeBWorK. The are used by the Apache configuration and by the system itself. Many other settings rely on these variables:<br />
<br />
{| border="1"<br />
|-<br />
| '''variable''' || '''description''' <br />
|-<br />
| <code>$webwork_url</code> || The URL associated with the WeBWorK handler. Usually <code>/webwork2</code>. <br />
|-<br />
| <code>$pg_root</code> || The path to the PG directory. Usually <code>/opt/webwork/pg</code>. <br />
|-<br />
| <code>$webwork_htdocs_url</code> || The URL of static WeBWorK hypertext files. Usually <code>/webwork2_files</code>. <br />
|-<br />
| <code>$webwork_htdocs_dir</code> || The path to the static WeBWorK hypertext files. Usually <code>$webwork_dir/htdocs</code>. <br />
|-<br />
| <code>$webwork_courses_url</code> || The URL of the courses directory. Usually <code>/webwork2_course_files</code>. <br />
|-<br />
| <code>$webwork_courses_dir</code> || The path to the courses directory. Usually <code>$webwork_dir/courses</code>. <br />
<br />
|}<br />
<br />
=== Paths to external programs ===<br />
<br />
To avoid executing malicious code, WW calls external programs using full path names.<br />
<br />
{| border="1"<br />
|-<br />
| '''variable''' || '''description''' <br />
|-<br />
| <code>$externalPrograms{mkdir}</code> || Path to <code>mkdir</code> binary. Usually <code>/bin/mkdir</code>. <br />
|-<br />
| <code>$externalPrograms{mysql}</code> || Path to <code>mysql</code> binary. Usually <code>/usr/bin/mysql</code> or <code>/usr/local/bin/mysql</code>. <br />
|-<br />
| <code>$externalPrograms{tar}</code> || Path to <code>tar</code> binary. Usually <code>/usr/bin/tar</code>. <br />
|-<br />
| <code>$externalPrograms{latex}</code> || Path to <code>latex</code> binary. Usually <code>/usr/bin/latex</code> or <code>/usr/local/bin/latex</code>. <br />
|-<br />
| <code>$externalPrograms{pdflatex}</code> || Path to <code>pdflatex</code> binary. Usually <code>/usr/bin/pdflatex</code> or <code>/usr/local/bin/pdflatex</code>. <br />
|-<br />
| <code>$externalPrograms{dvipng}</code> || Path to <code>dvipng</code> binary. Usually <code>/usr/bin/dvipng</code> or <code>/usr/local/bin/dvipng</code>. <br />
|-<br />
| <code>$externalPrograms{tth}</code> || Path to <code>tth</code> binary. Usually <code>/usr/bin/tth</code> or <code>/usr/local/bin/tth</code>. <br />
|-<br />
| <code>$externalPrograms{giftopnm}</code> || Path to <code>giftopnm</code> binary. Usually <code>/usr/bin/giftopnm</code> or <code>/usr/local/bin/giftopnm</code>. <br />
|-<br />
| <code>$externalPrograms{ppmtopgm}</code> || Path to <code>ppmtopgm</code> binary. Usually <code>/usr/bin/ppmtopgm</code> or <code>/usr/local/bin/ppmtopgm</code>. <br />
|-<br />
| <code>$externalPrograms{pnmtops}</code> || Path to <code>pnmtops</code> binary. Usually <code>/usr/bin/pnmtops</code> or <code>/usr/local/bin/pnmtops</code>. <br />
|-<br />
| <code>$externalPrograms{pnmtopng}</code> || Path to <code>pnmtopng</code> binary. Usually <code>/usr/bin/pnmtopng</code> or <code>/usr/local/bin/pnmtopng</code>. <br />
|-<br />
| <code>$externalPrograms{pngtopnm}</code> || Path to <code>pngtopnm</code> binary. Usually <code>/usr/bin/pngtopnm</code> or <code>/usr/local/bin/pngtopnm</code>. <br />
<br />
|}<br />
<br />
=== Mail settings ===<br />
<br />
WW sends mail in three instances. The PG system sends mail to report answers to questionnaires and free-response problems. The mail merge module is used to send mail to course participants, i.e. to report scores. The feedback module allows participants to send mail to course instructors.<br />
<br />
To send mail, WW needs the address of an SMTP server. When connecting to the SMTP server, it must also send an email address representing the sender of the email.<br />
<br />
{| border="1"<br />
|-<br />
| '''variable''' || '''description''' <br />
|-<br />
| <code>$mail{smtpServer}</code> || The address of an SMTP server. If the local machine is running an SMTP server (as is likely), use <code>localhost</code>. <br />
|-<br />
| <code>$mail{smtpSender}</code> || The address to send when connecting to the SMTP server. This has nothing to do with the <code>From</code> address on the mail message. <br />
<br />
|}<br />
<br />
=== Database settings ===<br />
<br />
The following settings are used in connecting to the MySQL database.<br />
<br />
{| border="1"<br />
|-<br />
| '''variable''' || '''description''' <br />
|-<br />
| <code>$database_dsn</code> || The location of the WeBWorK database. Usually <code>dbi.mysql.webwork</code>. See the Perl DBI documentation for more information about DSNs. <br />
|-<br />
| <code>$database_username</code> || The username to use when connecting to the database. Usually <code>webworkWrite</code>. <br />
|-<br />
| <code>$database_password</code> || The password to use when connecting to the database. Use a secure, random password of sufficient length. <br />
<br />
|}<br />
<br />
The <code>$dbLayoutName</code> variable controls the default database layout that will be used for new courses. If you plan to use MoodleIntegration on all new courses, set this to "sql_moodle". Otherwise, leave it set to the default, "sql_single".<br />
<br />
You can override the default when creating a new course.<br />
<br />
=== Timezone setting ===<br />
<br />
You can set the local timezone to use when displaying times using the <code>$siteDefaults{timezone}</code> setting. To get a list of timezone names, run:<br />
<br />
$ perl -MDateTime::TimeZone -e 'print join "\n", DateTime::TimeZone::all_names'<br />
<br />
To get a list of valid timezone "links" (deprecated names), run:<br />
<br />
$ perl -MDateTime::TimeZone -e 'print join "\n", DateTime::TimeZone::links'<br />
<br />
Links can be shorter and more familiar, but they may be ambiguous.<br />
<br />
=== Display modes ===<br />
<br />
WeBWorK has several techniques for displaying homework problems. Which of these modes is available is controlled by the <code>$pg{displayModes}</code> list. To disable a display mode, comment out its line from the list by inserting a <code>#</code> character at the beginning of the line.<br />
<br />
The supported display modes are as follows:<br />
<br />
{| border="1"<br />
|-<br />
| '''display mode''' || '''status''' || '''description''' <br />
|-<br />
| <code>plainText</code> || STABLE || This mode shows the raw TeX source of mathematics. It is useful for debugging. <br />
|-<br />
| <code>formattedText</code> || DEPRECATED || This mode uses the <code>tth</code> program to represent mathematics as HTML table structures. Output quality depends on the browser. There are typically font problems on the Mac platform. <br />
|-<br />
| <code>images</code> || STABLE || This mode uses the <code>dvipng</code> program to represent mathematics as PNG images. This gives excellent output on all browsers, but uses more bandwidth, as the images must be sent to the client. <br />
|-<br />
| <code>jsMath</code> || STABLE || This mode uses jsMath to display mathematics. The raw TeX is sent to the client, where a JavaScript program displays it. This requires the client to have a decent JavaScript implementation, and can be slow on older machines. <br />
|-<br />
| <code>asciimath</code> || DEPRECATED || This mode converts mathematics to ASCIIMath on the server and uses a <nobpo>JavaScript to convert them to MathML on the client. Requires a Mozilla-based browser or MSIE with the MathPlater plugin. <br />
|-<br />
| <code>LaTeXMathML</code> || EXPERIMENTAL || This mode is a modification of the <code>asciimath</code> mode that skips the intermediate ASCIIMath form. Requires a Mozilla-based browser or MSIE with the MathPlater plugin. <br />
<br />
|}<br />
<br />
=== jsMath settings ===<br />
<br />
When a student doesn't have the TeX fonts installed, jsMath can display a warning message pointing to the jsMath font download site. Since the image-mode fallback method is of high enough quality, most students will not feel the need to download and install the fonts, so this warning message is disabled by default. (It tended to worry the students, and there is a link to the download page on the control panel that is new in version 2.0 of jsMath).<br />
<br />
jsMath settings are stored in the <code>$pg{displayModeOptions}{jsMath}</code> hash:<br />
<br />
{| border="1"<br />
|-<br />
| '''variable''' || '''description''' <br />
|-<br />
| <code>reportMissingFonts</code> || Set to 1 if you want to have a message displayed for students who don't have the TeX fonts installed. The warning will only be shown on the first page they view that used jsMath (and there is a "hide" button that they can use to hide it even on that page). They can use the control panel to disable the warning messages permanently for their computer, if they want, so even if you turn on the warning message, it is not too intrusive. <br />
|-<br />
| <code>missingFontMessage</code> || An HTML string that will be used for the missing font message (when <code>reportMissingFonts</code> is non-zero). This string will replace the default warning message, and can be used to point to your own page of instructions for getting the fonts, for example, or for using the control panel to disable the warning. <br />
|-<br />
| <code>noImageFonts</code> || Set to 1 to prevent jsMath from using the image fallback method. This can be useful if you elected not to unpack the <code>jsMath-fonts.tar.gz</code> archive. <br />
|-<br />
| <code>processDoubleClicks</code> || By default, double-clicking on the math expression will display the TeX source that generated it. If you wish to disable this behavior, set this to 0. (Note that the raw TeX is still available in the page's HTML source.) <br />
<br />
|}<br />
<br />
== Configuring the database ==<br />
<br />
WeBWorK uses a single MySQL database to store course data. By default, this database is named <code>webwork</code> and is accessed by a MySQL user named <code>webworkWrite</code>.<br />
<br />
=== Creating a new database ===<br />
<br />
If this is a new installation, you must create the <code>webwork</code> database:<br />
<br />
$ mysql -u root -p mysql<br />
Password: '''***'''<br />
> CREATE DATABASE webwork;<br />
> GRANT SELECT, INSERT, UPDATE, DELETE, CREATE, ALTER, DROP, LOCK TABLES<br />
ON webwork.* TO webworkWrite@localhost IDENTIFIED BY 'password';<br />
> exit<br />
Bye<br />
$ <br />
<br />
(Replace <code>password</code> with the password you set for <code>$database_password</code> in <code>global.conf</code>.)<br />
<br />
=== Using an existing database ===<br />
<br />
If you already have a <code>webwork</code> database from WeBWorK 2.1.x or 2.2.x, you must run the utility <code>wwdb_check</code> to make sure that it is up-to-date for use with 2.4.x. You should '''not''' use this utility if you are upgrading from 2.3.x or an earlier version of 2.4.x. (For example, from 2.4.1 to 2.4.2.)<br />
<br />
To run the utility:<br />
<br />
$ /opt/webwork/webwork2/bin/wwdb_check<br />
<br />
The script will look at the structure of your <code>webwork</code> database, and alert you to missing tables, missing fields, and incorrect field types. You will have the option to fix these problems.<br />
<br />
WeBWorK 2.4 requires permision to <code>LOCK TABLES</code> in the <code>webwork</code> database. Use the <code>mysql</code> console to add it:<br />
<br />
$ mysql -u root mysql<br />
Password: '''***'''<br />
> GRANT LOCK TABLES ON webwork.* TO webworkWrite@localhost;<br />
> exit;<br />
$<br />
<br />
=== Automated database initialization and upgrade ===<br />
<br />
WeBWorK 2.3.0 introduces an automatic database upgrade system. Rather than manually issuing SQL commands to make changes to the database, or using ad-hoc scripts like <code>wwdb_addgw</code>, there is a single script called <code>wwdb_upgrade</code> that applies any necessary updates. It should be run when creating a new database, and any time you upgrade WeBWorK.<br />
<br />
$ /opt/webwork/webwork2/bin/wwdb_upgrade<br />
<br />
Add the <code>-v</code> switch to get more information about what the script is doing.<br />
<br />
=== Image depths database ===<br />
<br />
The "images" display mode has the capability to store depth information in a <code>depths</code> table when equation images are generated. The information allows better alignment of images with surrounding text. In previous versions of WeBWorK, the <code>depths</code> table was stored in a separate database, named <code>DvipngDepths</code>. Starting with WeBWorK 2.3.0, it is stored in the <code>webwork</code> database itself.<br />
<br />
If you are upgrading an existing installation, and you had set <code>$pg{displayModeOptions}{images}{dvipng_align}</code> to <code>mysql</code> in the old version, you have depths information stranded in your old <code>DvipngDepths</code> database, and existing images will lose access to this information.<br />
<br />
The easiest way to solve this is to delete the existing images. This is probably a good idea anyway when upgrading since existing images won't take advantage of rendering improvements, dvipng improvements, etc. To delete the images:<br />
<br />
$ /opt/webwork/webwork2/bin/remove_stale_images --days=0 --delete<br />
<br />
== Configuring Apache ==<br />
<br />
=== Testing mod_perl ===<br />
<br />
To verify that mod_perl is installed, you can use mod_info to list the installed modules. If mod_info itself is disabled or not installed, you can either install/enable it, or skip this test and check using Apache::Status instead. The process for installing and enabling modules varies by distribution. To configure mod_perl, uncomment the location block <code>&lt;Location /server-info&gt;</code> in your Apache config file (usually <code>httpd.conf</code> or <code>apache.conf</code>). It should look something like this:<br />
<br />
<Location /server-info><br />
SetHandler server-info<br />
Order deny,allow<br />
Deny from all<br />
Allow from localhost<br />
Allow from .yourschool.edu<br />
</Location><br />
<br />
You may have to add the <code>Order</code>, <code>Deny</code>, and <code>Allow</code> lines yourself, or there may already be lines there you can customize. Restart Apache (<code>apachectl graceful</code>) and visit <code>http://yourserver.yourschool.edu/server-info</code>. You should see an entry in the list of active modules for mod_perl.<br />
<br />
To further test mod_perl, you can install the Perl module Apache::Status. After installing, add the following section to your Apache config file:<br />
<br />
<Location /perl-status><br />
SetHandler perl-script<br />
PerlHandler Apache::Status<br />
Order deny,allow<br />
Deny from all<br />
Allow from localhost<br />
Allow from .yourschool.edu<br />
</Location><br />
<br />
Restart Apache (<code>apachectl graceful</code>) and visit <code>http://yourserver.yourschool.edu/perl-status</code>. You should see a page listing various information about mod_perl.<br />
<br />
=== Enabling WeBWorK ===<br />
<br />
Once mod_perl is working, Apache must be configured to handle requests for WeBWorK. Apache provides access to WeBWorK through three URL locations:<br />
<br />
* The location that is handled by the <code>Apache::WeBWorK</code> module, usually <code>/webwork2</code>.<br />
* The location of system-wide resources, usually <code>/webwork2_files</code>.<br />
* The location of course-specific resources, usually <code>/webwork2_course_files</code>.<br />
<br />
WeBWorK ships with an Apache config file that you can include in your main Apache config file. The file is named <code>webwork.apache-config.dist</code> and located in the <code>conf</code> directory. First, copy the file to <code>webwork.apache-config</code>:<br />
<br />
$ cd /opt/webwork/webwork2/conf<br />
$ cp webwork.apache-config.dist webwork.apache-config<br />
<br />
Then, edit the copy to set the <code>$webwork_dir</code> variable to the path of the directory containing the WeBWorK installation. This is usually <code>/opt/webwork/webwork2</code>. This value is used to read the WeBWorK configuration file and get the rest of the configuration data.<br />
<br />
Further down in the file, you may want to customize the directives used to define the association between Apache and WeBWorK. Specifically, you may need to add the following to the <code>&lt;ocation&gt;</code> and <code>&lt;Directory&gt;</code> stanzas, to permit access:<br />
<br />
Order allow,deny<br />
Allow from all<br />
<br />
After editing <code>webwork.apache-config</code>, append the following line to your Apache configuration file:<br />
<br />
Include /opt/webwork/webwork2/conf/webwork.apache-config<br />
<br />
If you are upgrading from a previous version of WeBWorK which did not use the <code>webwork.apache-config</code> file, you will need to remove the WeBWorK-related directives from your Apache configuration.<br />
<br />
Then restart Apache and test your configuration:<br />
<br />
* Test the <code>/webwork2</code> location by visiting <code>http://yourserver.yourschool.edu/webwork2</code>. You should see the WeBWorK home page, with no courses listed.<br />
* Test the <code>/webwork2_files</code> location by visiting <code>http://yourserver.yourschool.edu/webwork2_files</code>. You should see the "WeBWorK Placeholder Page".<br />
* You cannot test the <code>/webwork2_course_files</code> location until you have created a course.<br />
<br />
=== Experimental support for Apache 2.0.x ===<br />
<br />
If you are using Apache 2.0.x, follow the directions above, with these changes:<br />
<br />
Enable the libapreq module by adding the following line to your Apache2 configuration file. Place this line with the other <code>LoadModule</code> lines.<br />
<br />
LoadModule apreq_module modules/mod_apreq.so<br />
<br />
Use the module Apache2::Status in place of Apache::Status.<br />
<br />
Use the file <code>webwork.apache2-config</code> in place of <code>webwork.apache-config</code>.<br />
<br />
== Creating the admin course ==<br />
<br />
WeBWorK includes web-based course management tools. Access to these tools is controlled by a special course named <code>admin</code>. The instructors in this course are permittied to perform administrative functions. If the admin course exists, a '''Course Administration''' link will appear on the WeBWorK home page.<br />
<br />
If you created a <code>wwadmin</code> group, create the admin course as follows:<br />
<br />
$ cd /opt/webwork/courses<br />
$ newgrp wwadmin<br />
$ umask 2<br />
$ addcourse<br />
$ addcourse admin --db-layout=sql_single --users=adminClasslist.lst --professors=admin<br />
$ exit<br />
<br />
If you did not create a <code>wwadmin</code> group, create the admin course as follows:<br />
<br />
$ sudo -u www-data addcourse admin --db-layout=sql_single --users=adminClasslist.lst --professors=admin<br />
<br />
Replace <code>www-data</code> with the user your webserver runs as.<br />
<br />
See CourseAdministrationManual#Permissions_issues for more about getting the permission right when using the command-line tools.<br />
<br />
After you create the course, visit the WeBWorK home page on your server, usually located at <code>http://yourserver.yourschool.edu/webwork2</code>. Click on the '''Course Administration''' link. You can also access the admin course directly, at <code>http://yourserver.yourschool.edu/webwork2/admin</code>.<br />
<br />
To log in, enter <code>admin</code> for your username and <code>admin</code> for your password. Once logged into the admin course, the first thing you should do is change the password for the admin account. You can do this by clicking the '''Password/Email''' link on the links menu. After you do this, you may add accounts for any additional people who should have administrative access using the '''Class List Editor''' link. <br />
<br />
== Where to go from here ==<br />
<br />
Read [[Course Administration]] for more information about managing courses.<br />
<br />
Read [[Problem Libraries]] for information on installing libraries of pre-written WeBWorK problems.<br />
<br />
Read [[Moodle Integration]] for information on including WeBWorK problem sets in Moodle courses. (Experimental)<br />
<br />
Read [[LDAP Authentication]] for information about LDAP authentication. (Experimental)<br />
<br />
Consult [[:Category:Administrators]] for other WeBWorK documentation for system administrators.<br />
<br />
[[Category:Installation Manuals]]</div>Xiong Chiamiovhttps://webwork.maa.org/mediawiki_new/index.php?title=Installation_Manual_for_2.4_on_Ubuntu_8.04&diff=3266Installation Manual for 2.4 on Ubuntu 8.042008-07-03T15:20:33Z<p>Xiong Chiamiov: /* Ubuntu Software Packages */</p>
<hr />
<div>These instructions cover the installation of the Ubuntu Linux 8.04 operating system and WeBWorK 2.4 from scratch. <br />
<br />
They 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.<br />
<br />
== Notation ==<br />
<br />
First some short comments on notation we will be using. We will use <code>&lt;key&gt;</code> to indicate that you should press a specific key (e.g. <code>&lt;Enter&gt;</code>, <code>&lt;Tab&gt;</code>, <code>&lt;F12&gt;</code>, etc.). Sometimes we will also use e.g. <code>&lt;root password&gt;</code> to indicate you have to enter the root password.<br />
<br />
<code>^</code> will indicate the <code>&lt;Ctrl&gt;</code> key so e.g. <code>^X</code> is really shorthand for <code>&lt;Ctrl&gt; &lt;X&gt;</code>, i.e. press the Ctrl key and hit the X key.<br />
<br />
We will give references to specific versions of software, e.g. httpd-2.2.4.tar.gz rather than the more general httpd-2.x.x.tar.gz. In most cases you should be able to use the latest stable version but we have only tested the versions listed.<br />
<br />
== Installing the Ubuntu 8.04 Linux Operating System ==<br />
<br />
===Installation CD ===<br />
Obtain the <code>Desktop Edition, Alternate</code> installation DVD/CD set. Connect to http://www.ubuntu.com/ for information. On the download page http://www.ubuntu.com/getubuntu/download make sure you check the box for <code>Check here if you need the alternate desktop CD. This CD does not include the Live CD, instead it uses a text-based installer</code>. For example you can use wxDownload Fast or BitTorrent to download an ISO image of the installation CD and then burn your own installation CD. 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/7.04/MD5SUMS). wxDownload Fast automatically calculates the MD5 checksums which is convenient. I have had good luck downloading from mirrors.kernel.org but your experience may differ. These instructions will assume you have the installation CD but installing from a commercial DVD/CD set or from the net should be essentially identical.<br />
<br />
Place the installation CD in your DVD/CD drive and reboot your computer from the DVD drive. You may have to press <code>&lt;F12&gt;</code> 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.<br />
<br />
First select <code>English</code> by just hitting <code>&lt;Enter&gt;</code>.<br />
<br />
You will see a list of options. <br />
<br />
# If you want hit <code>&lt;F1&gt;</code> to obtain help and see additional boot methods<br />
# You can just hit <code>&lt;Enter&gt;</code> to accept the default install method except in the following situation<br />
# If your network has DHCP enabled but you want to setup your server with a static IP address, then hit <code>&lt;F6&gt;</code> and on the <code>Boot OPtions</code> line move the cursor before <code>quiet --</code> and type <code>netcfg/disable_dhcp=true</code> , leave a space before <code>quiet</code> and then hit <code>&lt;Enter&gt;</code><br />
# A succession of pages follow, for each select the obvious option and hit <code>&lt;Enter&gt;</code>. For example my obvious options are <code>English</code>, <code>United States</code>, <code>&lt;No&gt;</code>, <code>USA</code> and <code>USA</code> <br />
# The system will than scan your CD and load various components<br />
# If your system has multiple network interfaces, you will be asked to select the one to be used during the installation (which will usually be a hard wired ethernet connection)<br />
# Unless you entered the <code>netcfg/disable_dhcp=true</code> boot option above, the system will try to configure your network using DHCP. If you have DHCP, your network interface will be set up automatically. If you don't have DHCP, automatic network configuration will fail quickly (or just hit <code>&lt;Enter&gt;</code> to <code>Cancel</code> if you are impatient). Then hit <code>&lt;Enter&gt;</code> to <code>Continue</code><br />
<br />
'''Manual network configuration'''. If your network interface was set up automatically by DHCP, you can skip the rest of this paragraph. Otherwise you will have to enter your machine's static ip address, etc. To do this<br />
# Select <code>Configure network manually</code><br />
# Enter your computer's IP address and use <code>&lt;Tab&gt;</code> to select <code>Continue</code><br />
# The <code>netask</code> is probably OK as it but another possibility may be 255.255.0.0<br />
# Enter the ip address of your gateway router. Ubuntu makes a good guess at this, but your network may be set up differently.<br />
# Next enter the ip address(es) of up to 3 nameservers separated by spaces (at a minimum you have to enter the ip address one nameserver)<br />
# Enter the name of your server<br />
# Enter the domain name for the domain your server sits on (e.g. math.myschool.edu)<br />
# This completes the static ip address setup<br />
<br />
Now select your time zone and wait for the clock to be configured<br />
<br />
===Optional Configurations===<br />
<br />
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.<br />
<br />
'''Optional A''' creates a separate partition 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 means that it is easier and faster to back up other partitions and skip backing up unnecessary files.<br />
<br />
'''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.<br />
<br />
'''Optional C''' configures Apache so that access to WeBWorK will be through an encrypted Secure Sockets Layer (SSL) with an https: URL.<br />
<br />
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.<br />
<br />
===Partition disks===<br />
Next comes the <code>Partition disks</code> 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. <br />
<br />
'''Optional A''': The default partitioning scheme creates just two partitions, a root (<code>/</code>) partition and a swap partition. Here we will create those and an additional partition for WeBWorK's temporary files.<br />
<br />
# On the <code>Partition disks</code> page use <code>&lt;Tab&gt;</code> to select <code>Go Back</code> and then select <code>Partition disks</code> <br />
# Use the down arrow to select your disk (<code>sda</code>)<br />
# On the <code>You have selected an entire device to partition...</code> page select <code>Yes</code> to the question <code>Create new empty partition table on this device</code><br />
# On the <code>This is an overview...</code> page select <code>FREE SPACE</code><br />
# On the <code>How to use this free space</code> page select <code>Create a new partition</code><br />
# 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 (<code>/</code>) partition. Actually if you are going through the trouble of doing this, you probably will want to research other partitioning recommendations.<br />
# On the <code>The maximum size you can use...</code> page enter the size for your root (<code>/</code>) partition and <code>Continue</code><br />
# Select <code>Primary</code> for the type of the new partition<br />
# Select <code>Beginning</code> for the location of the new partition<br />
# Select <code>/</code> for the Mount point of the new partition and then select <code>Done setting up the partition</code><br />
<br />
Now we repeat the process for the partition which will hold WeBWorK's temporary files.<br />
# On the <code>This is an overview...</code> page select <code>FREE SPACE</code><br />
# On the <code>How to use this free space</code> page select <code>Create a new partition</code><br />
# On the <code>The maximum size you can use...</code> page enter the size for WeBWorK's temporary files partition. As we said 25 GB for every 1,000 students should be ample. Then <code>Continue</code><br />
# Select <code>Logical</code> for the type of the new partition<br />
# Select <code>Beginning</code> for the location of the new partition<br />
# Select <code>Mount point</code> and then hit <code>&lt;Enter&gt;</code><br />
# Select <code>Enter manually</code> and then hit <code>&lt;Enter&gt;</code><br />
# For the <code>Mount point for this partition</code> enter <code>/var/www/wwtmp</code> and <code>Continue</code><br />
# Then select <code>Done setting up the partition</code><br />
<br />
Finally we set up the swap partition<br />
# On the <code>This is an overview...</code> page select <code>FREE SPACE</code><br />
# On the <code>How to use this free space</code> page select <code>Create a new partition</code><br />
# On the <code>The maximum size you can use...</code> 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 <code>Continue</code><br />
# Select <code>Logical</code> for the type of the new partition<br />
# Select <code>Beginning</code> for the location of the new partition<br />
# Select <code>Use as</code> and then hit <code>&lt;Enter&gt;</code><br />
# Select <code>swap area</code> and then hit <code>&lt;Enter&gt;</code><br />
# Then select <code>Done setting up the partition</code><br />
<br />
Finally <br />
# Review your changes and<br />
# Select <code>Finish partitioning and write changes to disk</code> and then hit <code>&lt;Enter&gt;</code><br />
# Select <code>Yes</code> to confirm the changes<br />
<br />
===Base Installation===<br />
# Now the base installation takes place --- this takes a short time<br />
# Enter yourself as a user (with user name and password). Note this account will function partially as the <code>root</code> account so you might want to pick a different username and password than you regularly use. <br />
# You can probably leave the HTTP proxy information blank<br />
# Now sit back and relax while a lot of software is installed --- this takes awhile<br />
<br />
The final step is to install the boot loader. I have a non standard setup and for some reason I had trouble installing the Grub boot loader but Lilo worked fine. Almost certainly, Grub will work fine for you<br />
<br />
===Continue Installation ===<br />
After this finishes the system will eject the CD and ask you to reboot. <br />
<br />
# Log into your account <br />
# Accept any available updates. You may see a little notification icon (it has a arrow on it) to the right of your name in the upper right hand corner of the screen --- click on it. Alternately you can select <code>System</code>, <code>Administration</code>, <code>Update Manager</code>. Click <code>install Updates</code>. You may have to enter the <code>&lt;your password&gt;</code> which functions as the <code>&lt;root password&gt;</code> . Follow any instructions, e.g. you may be told to reboot as soon as the installation is completed (to reboot, select <code>System</code>, <code>Quit</code> and then <code>Restart</code>)<br />
<br />
===Test Browser and Keyboard ===<br />
<br />
After reboot and login, click on <code>Applications</code>, <code>Internet</code>, <code>Firefox Web Browser</code> (or just click the Firefox icon at the top of the screen) and you should be connected to the world. <br />
Goto <br />
http://webwork.maa.org/wiki/Installation_Manual_for_2.4_on_Ubuntu_8.04<br />
where you can view this document and, if you want, copy commands that you need (see below).<br />
<br />
If something is wrong and you are not connected to the web, the first thing to do is check that you entered the correct network information.<br />
# Select <code>System</code>, <code>Administration</code>, <code>Network</code><br />
# Click on <code>Unlock</code><br />
# Enter <code>&lt;your password&gt;</code> and click <code>Authenticate</code><br />
# Select <code>Wired connection</code> and click <code>Properties</code><br />
# Check that all the entries are correct and edit them if they are not<br />
# Then click <code>OK</code><br />
# Next click on <code>DNS</code> and check the name server entries and correct if necessary<br />
# Click on <code>Close</code> to close <code>Network settings</code><br />
Your network connection should start up almost immediately. If you are still having problems it's time to investigate further or seek help.<br />
<br />
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. Click <code>System</code>, <code>Preferences</code>, <code>Keyboard</code> and then increase the delay time interval and hit <code>Close</code>.<br />
<br />
== Terminal Window Notation and Use ==<br />
<br />
Before installing and configuring additional software, we need to talk about terminal windows.<br />
<br />
To open a terminal window click <code>Applications</code>, <code>Accessories</code> and then select <code>Terminal</code>.<br />
<br />
In a terminal window some commands will have to be run as root whereas<br />
others should be run as a regular user. We will use # to indicate<br />
that the command is to be run as root e.g.<br />
<br />
# perl -MCPAN -e shell<br />
<br />
and $ to indicate that the command is to be run as a normal user e.g.<br />
<br />
$ cp .bashrc .bashrc.bak1<br />
<br />
To execute the above commands you have to hit <code>&lt;Enter&gt;</code>. We'll just assume this. <br />
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.<br />
<br />
The bash shell which you will be using has a number of very<br />
convenient features.<br />
<br />
One is command and file name completion. If you are typing (e.g.<br />
<code>ch</code>) and hit <code>&lt;tab&gt;</code> bash will complete the command or filename if it is<br />
unambiguous (or more precisely it will complete as much as possible).<br />
If there are multiple possibilities (as in the case of <code>ch</code>) nothing will<br />
happen (except you may hear a beep) and you can type more letter(s) and hit <code>&lt;tab&gt;</code> again. Or you can<br />
hit <code>&lt;tab&gt;</code> a second time and you will see a list of all possible<br />
completions. E.g. entering <code>ch&lt;tab&gt;&lt;tab&gt;</code> gives a list of possible<br />
completions and <code>ch&lt;tab&gt;g&lt;tab&gt;</code> (or <code>chg&lt;tab&gt;</code>) gives <code>chgrp</code>, the change group command. This<br />
is very fast and convenient and it also leads to fewer typing errors.<br />
<br />
Another useful shortcut is the command history. Using the up and down<br />
arrow keys will bring up previous commands which can be edited and then<br />
executed. If you are repeating a command or entering a command which<br />
is similar to a previous one, this is very useful.<br />
<br />
You can copy commands from these instructions (with <code>copy</code> from the Edit dropdown list or <code>^C</code>) and paste them into a terminal window<br />
(with <code>paste</code> from the Edit dropdown list or <code>&lt;Shift&gt; &lt;Ctrl&gt; &lt;V&gt;</code>). However typing yourself using command completion is probably just as fast except if a command is long.<br />
<br />
By default Ubuntu has no password set for the root user. To gain root access you have to type in your own user password. This is the password you set for the first user while installing Ubuntu. However we will<br />
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:<br />
<br />
$ sudo passwd<br />
Password: <your password><br />
<br />
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'''.<br />
<br />
Enter new UNIX password: <root password><br />
Retype new UNIX password: <root password><br />
passwd: Password updated successfully<br />
$<br />
<br />
To test this <br />
<br />
$ su<br />
Password: <root password><br />
# whoami<br />
root<br />
#exit<br />
$<br />
<br />
Finally perhaps a safer way to run commands as <code>root</code> is to use the <code>sudo</code> command<br />
<br />
$ sudo <command><br />
Password: <your password><br />
<br />
After you enter the password the command is executed. For a certain period (maybe 5 minutes) you can execute additional <code>sudo</code> commands without reentering <code>&lt;your password&gt;</code>. A log of all <code>sudo</code> commands is kept (I don't know where). In these instructions for the most part we will not use <code>sudo</code>, but keep it in mind for other times that you have to become <code>root</code> in order to execute a few commands (e.g. restarting <code>Apache</code>).<br />
<br />
Note that for certain GUI tools such as the <code>Synaptic Package Manager</code> that require root access, the password required is <code>&lt;your password&gt;</code>, the password for the first account you set up, not the new <code>&lt;root password&gt;</code>.<br />
<br />
For our next terminal window task create a <code>downloads</code> directory where we will keep copies of downloaded software.<br />
<br />
$ cd<br />
$ mkdir downloads<br />
<br />
==Ubuntu Software Packages ==<br />
<br />
Our next task is to install a number of Ubuntu software packages.<br />
<br />
# Select <code>System</code>, <code>Administration</code> and then <code>Synaptic Package Manager</code>. You will have to enter the <code>&lt;your password&gt;</code>. The <code>Synaptic Package Manager</code> window will open<br />
# Click on <code>Reload</code> to bring the package information up to date<br />
<br />
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 <code>libnet-ldap-perl</code> and then just give the list of required packages.<br />
<br />
# Select <code>Search</code> <br />
# Under <code>Look in:</code> select <code>Name</code>. The default <code>Description and Name</code> sometimes returns too many possibilities<br />
# We are searching for <code>libnet-ldap-perl</code> so enter <code>ldap-perl</code> (or something similar; you can copy and paste from this document if you want) and click on <code>Search</code><br />
# This should result in 3 possibilities. Select and Mark for Installation (by double clicking or checking and then selecting <code>Mark for Installation</code>) <code>libnet-ldap-perl</code>. You will see a pop up window <code>Mark additional required changes?</code> and you should always click <code>Mark</code> to accept the requirements.<br />
# Follow this basic procedure for all the packages listed below<br />
<br />
Here is the list of Debian packages that need to be installed. See [[Installation Manual for 2.4]] for a short explanation of what most of these packages do. <br />
<br />
# <code>apache2</code><br />
# <code>apache2-mpm-prefork</code><br />
# <code>cvs</code><br />
# <code>dvipng</code><br />
# <code>libapache2-request-perl</code><br />
# <code>libdatetime-perl</code><br />
# <code>libdbd-mysql-perl</code><br />
# <code>libemail-address-perl</code><br />
# <code>libextutils-xsbuilder-perl</code><br />
# <code>libgd-gd2-perl</code><br />
# <code>libmail-sender-perl</code><br />
# <code>libnet-ldap-perl</code><br />
# <code>libossp-uuid-perl</code><br />
# <code>libsql-abstract-perl</code><br />
# <code>libstring-shellquote-perl</code><br />
# <code>libtimedate-perl</code><br />
# <code>libxml-parser-perl</code><br />
# <code>libxml-writer-perl</code><br />
# <code>mysql-server-5.0</code><br />
# <code>netpbm</code><br />
# <code>openssh-server</code><br />
# <code>preview-latex-style</code><br />
# <code>tetex-bin</code><br />
# <code>tetex-extra</code><br />
<br />
When I do this I see on the bottom of <code>Synaptic Package Manager</code> window <code>82 to install/upgrade</code>, <code>1 to remove</code>. Your numbers may differ slightly. <br />
Now click <code>Apply</code> and <code>Apply</code> again to confirm the changes. You will be asked several times to enter a<br />
<code>New password for the MySQL "root" user</code>; just hit <code>&lt;Enter&gt;</code> which gives the default blank password. We will fix this and several other MySQL security issues below.<br />
<br />
That completes the set up of your base Ubuntu system. You can quit the <code>Synaptic Package Manager</code>.<br />
<br />
<br />
If you would prefer to install all of these packages in one fell swoop, run this command as root:<br />
<br />
<code># aptitude install apache2 apache2-mpm-prefork cvs dvipng libapache2-request-perl libdatetime-perl libdbd-mysql-perl libemail-address-perl libextutils-xsbuilder-perl libgd-gd2-perl libnet-ldap-perl libossp-uuid-perl libsql-abstract-perl libnet-ldap-perl libsql-abstract-perl libstring-shellquote-perl libtimedate-perl libxml-parser-perl libxml-writer-perl mysql-server-5.0 netpbm openssh-server preview-latex-style tetex-bin tetex-extra</code><br />
<br />
== Installing Perl Modules ==<br />
We now have to install several additional Perl modules which unfortunately are not available from the Debian package system.<br />
<br />
=== Testing Perl Modules ===<br />
To test if a Perl module is installed and working on your system, issue the following command, replacing <code>Module</code> with the name of the module:<br />
<br />
$ perl -MModule -e 'print "installed!\n"'<br />
<br />
If the module is installed you will see <code>installed!</code>. If not you will see at lot of gibberish. E.g. at this stage in our installation process <code>CPAN</code> is installed and <code>MXML::Parser::EasyTree</code> is not so<br />
<br />
$ perl -MCPAN -e 'print "installed!\n"'<br />
<br />
yields<br />
<br />
installed!<br />
<br />
and<br />
<br />
$ perl -MXML::Parser::EasyTree -e 'print "installed!\n"'<br />
<br />
yields<br />
<br />
Can't locate XML/Parser/EasyTree.pm in @INC (@INC contains: <br />
/etc/perl /usr/local/lib/perl/5.8.8 /usr/local/share/perl/5.8.8<br />
...<br />
<br />
=== Installing Additional Perl Modules from CPAN ===<br />
<br />
Be aware that in rare cases you might have to <br />
as root run<br />
<br />
$ su<br />
<root password><br />
# unset LANG<br />
# exit<br />
$<br />
<br />
since otherwise the installation of some modules (Module::Build is an example) may fail.<br />
<br />
First we will set up CPAN. For this you have to be root.<br />
<br />
$ su<br />
<root password><br />
# perl -MCPAN -e shell<br />
<br />
Since this is the first time you are using CPAN it will ask you <code>Are you ready for manual configuration?</code> <br />
Respond <code>no</code> and that should be it. <br />
<br />
Next we add at least one mirror and reload the index. A list of mirrors can be found at http://mirrors.cpan.org. To add the mirror ftp://mirrors.kernel.org/pub/CPAN and reload the index do the following. For me, a slow and inaccurate typist, copying (<code>^C</code>) and pasting (<code>&lt;Shift&gt; &lt;Ctrl&gt; &lt;V&gt;</code>) is much faster.<br />
<br />
cpan> o conf urllist push ftp://mirrors.kernel.org/pub/CPAN<br />
cpan> reload index<br />
<br />
Note that one time this failed when I tried to do it in the evening but when I tried again the next morning it worked fine. Now we update CPAN itself<br />
<br />
cpan> install Bundle::CPAN<br />
<br />
and always hit <code>&lt;Enter&gt;</code> to accept the defaults when prompted. This can be a long process with many long pauses. Please be patient. <br />
When you again see the <br />
<br />
cpan><br />
<br />
prompt enter<br />
<br />
cpan> reload cpan<br />
cpan> o conf commit<br />
<br />
Now install the following modules<br />
<br />
cpan> install XML::Parser::EasyTree Iterator Iterator::Util Net::IP <br />
<br />
and in case you are prompted accept all defaults by just hitting <code>&lt;Enter&gt;</code>. <br />
Note that with more than one module to install, we just list them after <code>install</code> separated by spaces.<br />
<br />
When you again see the <br />
<br />
cpan><br />
<br />
prompt enter<br />
<br />
cpan> exit<br />
#<br />
<br />
=== Installing Additional Perl Modules from Source ===<br />
At one point in time (August 2006), the installation of <code>DateTime</code> using CPAN was broken. Currently <code>DateTime</code> 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. <br />
<br />
'''IMPORTANT:''' With Debian we have already installed <code>DateTime</code> 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.<br />
<br />
Now we give the example of installing <code>DateTime</code> from source. As we said you can skip this part.<br />
<br />
Goto http://search.cpan.org/,<br />
search for <code>DateTime</code> and click on <code>DateTime</code>. Then near the top right download <code>DateTime-0.36.tar.gz</code> and save it to disk. Move it to your <code>downloads</code> directory. Then<br />
<br />
$ cd <br />
$ cd downloads<br />
$ tar -zvxf DateTime-0.36.tar.gz<br />
$ cd DateTime-0.36/<br />
<br />
<br />
$ perl Makefile.PL<br />
$ make<br />
$ make test<br />
<br />
If <code>make test</code> indicates something is missing you will have to install that. In fact in the case of <code>DateTime</code>, you would see that quite a few things are missing.<br />
<code>DateTime</code> requires the additional modules <code>version</code> , <code>Module::Build</code> , <code>Class::Singleton</code> , <code>DateTime::TimeZone</code> and <code>DateTime::Locale</code> . We could install these using CPAN<br />
<br />
# perl -MCPAN -e shell<br />
cpan> install version Module::Build Class::Singleton DateTime::TimeZone DateTime::Locale<br />
cpan> exit<br />
# exit<br />
$<br />
<br />
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<br />
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 <code>package/file.pm</code> was not found, you should serach for and install <code>package::file</code> since perl modules use a double colon (<code>::</code>) as a directory separator.<br />
<br />
Assuming all is OK<br />
<br />
$su<br />
<root password><br />
# make install<br />
# exit<br />
$<br />
<br />
Finally you should definitely test that the module (e.g. <code>DateTime</code>) was installed sucessfully<br />
<br />
$ perl -MDateTime -e 'print "installed!\n"'<br />
<br />
If you see <br />
<br />
installed!<br />
<br />
you can celebrate.<br />
<br />
== Apache 2 and mod_perl ==<br />
<br />
First we have to enable a couple Apache modules. Acting as <code>root</code> in a terminal window enter<br />
<br />
# a2enmod apreq<br />
# a2enmod info<br />
<br />
Next we make a copy of the configuration files for safekeeping. <br />
<br />
# cd /etc/apache2/mods-available<br />
# cp info.conf info.conf.bak1<br />
# cp status.conf status.conf.bak1<br />
<br />
Now we will edit configuration files <code>info.conf</code> and <code>status.conf</code> to allow us to view information about the setup and performance of the web server. Note that this is not absolutely necessary but it can be very useful. You can use your favorite editor but we will give instructions assuming you are using <code>gedit</code>. Note that you have to be root to edit these files. First we edit <code>info.conf</code><br />
<br />
# cd /etc/apache2/mods-available<br />
# gedit info.conf<br />
<br />
I suggest you allow access to server information from e.g. your department domain. To do this uncomment (i.e. remove the <code>#</code> from) <br />
# Allow from .example.com<br />
and then replace <code>.example.com</code> by <code>.math.yourschool.edu</code><br />
where of course you should edit <code>.math.yourschool.edu</code> appropriately. <br />
<br />
Then save the file and quit (<code>Save</code> and <code>File</code>, <code>Quit</code>).<br />
<br />
Now we edit <code>status.conf</code><br />
<br />
# cd /etc/apache2/mods-available<br />
# gedit status.conf<br />
<br />
After the comments at the top and above the <code><Location /server-status></code> line enter<br />
<br />
ExtendedStatus On<br />
<br />
Now edit the <br />
# Allow from .example.com<br />
line just as you did for <code>info.conf</code>.<br />
Then save the file and quit<br />
<br />
Now we have to set your server's fully qualified domain name. <br />
# Select <code>System</code>, <code>Administration</code>, <code>Network</code><br />
# Click on <code>Unlock</code><br />
# Enter <code>&lt;your password&gt;</code> and click <code>Authenticate</code><br />
# Click on <code>General</code><br />
# Under <code>Host name</code> enter <code>your_server_name</code> (if it's not already there)<br />
# Then under <code>Domain name</code> enter your server's domain name, something like <code>department.school.edu</code><br />
<br />
Next<br />
# Click on <code>Hosts</code><br />
#There should also be an entry with your server's IP address (if not you should add one)<br />
# Select the entry with your server's IP address and click <code>Properties</code><br />
# Under Aliases you should see your server's fully qualified domain name, something like <code>your_server_name.department.school.edu</code><br />
# Add or edit these entries if they are not correct<br />
# Then click <code>OK</code><br />
# And click <code>Close</code> to close <code>Network settings</code><br />
<br />
You can check these settings by running the commands<br />
<br />
$ hostname --fqdn<br />
<br />
and <br />
<br />
$ hostname<br />
<br />
The first respond with the fully qualified domain name and the second with just <code>your_server_name</code>.<br />
<br />
If the command <code>hostname --fqdn</code> returns <code>Unknown host</code> do the following:<br />
<br />
# Select <code>System</code>, <code>Administration</code>, <code>Network</code><br />
# Click on <code>Unlock</code><br />
# Enter <code>&lt;your password&gt;</code> and click <code>Authenticate</code><br />
# Click on <code>Hosts</code><br />
# Select the entry with your server's IP address and click <code>Properties</code><br />
# Under Aliases you should see your server's fully qualified domain name, something like <code>your_server_name.department.school.edu</code><br />
# Select the entry <code>127.0.0.1</code> and click <code>Properties</code><br />
# Under Aliases make sure you have the following entries in order<br />
## first your server's fully qualified domain name, something like <code>your_server_name.department.school.edu</code><br />
## second your server's name, something like <code>your_server_name</code><br />
## third <code>localhost</code><br />
# Click <code>Add</code> and add an entry with <code>IP address</code> <code>127.0.1.1</code> and under <code>Aliases</code> put your server's fully qualified domain name, something like <code>your_server_name.department.school.edu</code><br />
# Then click <code>OK</code><br />
# And click <code>Close</code> to close <code>Network settings</code><br />
<br />
Then check again by running the commands<br />
<br />
$ hostname --fqdn<br />
<br />
and <br />
<br />
$ hostname<br />
<br />
Note that if your server can not find its fully qualified domain name, certain tools (such as the Synaptic Package Manager) will not start.<br />
<br />
Now restart Apache<br />
<br />
$su<br />
<root password><br />
# apache2ctl graceful<br />
# exit<br />
$<br />
<br />
and test your server by connecting to<br />
"http://localhost/" and/or connecting to your<br />
server from a browser on a remote machine. You should see the page '''It works!''' indicating that Apache is running.<br />
<br />
You can check Apache's status by connecting to<br />
"http://localhost/server-status" using a browser on your machine or from a browser on a remote machine in the math.yourschool.edu domain.<br />
<br />
Further test Apache by connecting to<br />
"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 <br />
information about Apache. In particular under <code>Server Settings</code> you should see<br />
<br />
Server Version: Apache/2.2.8 (Ubuntu) mod_apreq2-20051231/2.6.0 mod_perl/2.0.3 Perl/v5.8.8<br />
<br />
indicating that both <code>mod_apreq2</code> and <code>mod_perl</code> are installed.<br />
<br />
If you have problems now or in the future, a good first thing to do is to look at the Apache error log which is located at <code>/var/log/apache2/error.log</code>. In the directory <code>/var/log/apache2/</code> you can "less" through the error log (<code>less error.log</code>), look at the last few entires (<code>tail error.log</code>) or run the command <code>tail -f error.log</code> which will display new error messages as they are appended to the file. Use <br />
<code>^C</code> to break out of <code>tail -f</code> .<br />
<br />
== Checking MySQL ==<br />
<br />
First check that MySQL is running by <br />
<br />
$ mysql -u root<br />
<br />
You should see<br />
<br />
Welcome to the MySQL monitor. Commands end with ; or \g.<br />
Your MySQL connection id is 1<br />
Server version: 5.0.51a-3ubuntu5 (Ubuntu)<br />
<br />
Type 'help;' or '\h' for help. Type '\c' to clear the buffer.<br />
<br />
mysql> <br />
<br />
Enter <code>exit</code> to exit<br />
<br />
mysql> exit<br />
Bye<br />
$<br />
<br />
== Reboot and Test ==<br />
<br />
Now reboot the system (<code>System</code>, <code>Quit</code>, <code>Restart</code>).<br />
<br />
Now connect to<br />
"http://localhost/" using a browser on your machine and/or to your<br />
server from a browser on a remote machine. You should see the page '''It Works''' indicating that Apache is running.<br />
<br />
This is also a good time to check that 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 <code>Keyboard Interactive</code> to the list of "Authentication methods" under "Authentication" if it's not already there. <br />
<br />
Finally test that MySQL is running.<br />
<br />
$ mysql -u root<br />
...<br />
mysql> <br />
mysql> exit<br />
Bye<br />
$<br />
<br />
Currently the MySQL password is empty so we didn't need a password.<br />
We will take care of that now.<br />
<br />
== MySQL Security Issuses ==<br />
As initially set up, MySQL is a very open system. There are anonymous accounts with full privileges for some databases and the root accounts are not password protected. See e.g. http://dev.mysql.com/doc/refman/5.0/en/default-privileges.html for information on this. We recommend removing the anonymous accounts and giving passwords to the root accounts. There are three root accounts, one is <code>root@localhost</code>, one is <code>root@127.0.0.1</code> and the third is <code>root@host_name</code> where <code>host_name</code> is the name of your server. To find this name, do the following <br />
<br />
$ mysql -u root<br />
mysql> SELECT Host, User, Password FROM mysql.user;<br />
<br />
You will see a table with six entries. For <code>localhost</code> you will see three Users, <code>root</code> and <code>debian-sys-maint</code> and one with an empty name (the anonymous user). The other listed Host (with a <code>root</code> user and also one with an empty name) is the name of your server which we will denote by <code>host_name</code>. <br />
<br />
First we will remove the anonymous accounts. <br />
<br />
mysql> DELETE FROM mysql.user WHERE User = <nowiki>''</nowiki>;<br />
mysql> FLUSH PRIVILEGES;<br />
<br />
Now using the up arrow key repeat the command<br />
<br />
mysql> SELECT Host, User, Password FROM mysql.user;<br />
<br />
and you should get a table with only four users (three <code>root</code> and one <code>debian-sys-maint</code>). <br />
<br />
Now we will assign a password to these <code>root</code> accounts. <br />
<br />
In the third command below, replace <code>host_name</code> with the name of the server host. In all commands replace <code>newpwd</code> with your choosen MySQL <code>root</code> password. As was said above, '''Do not forget what you enter here'''. Also remember that this is the password for the MySQL <code>root</code> user, not the Ubuntu linux system <code>root</code> user. Below we refer to this as <code>&lt;mysql root password&gt;</code><br />
<br />
mysql> UPDATE mysql.user SET password=PASSWORD('newpwd') WHERE host='localhost' and user='root';<br />
mysql> UPDATE mysql.user SET password=PASSWORD('newpwd') WHERE host='127.0.0.1' and user='root';<br />
mysql> UPDATE mysql.user SET password=PASSWORD('newpwd') WHERE host='host_name' and user='root';<br />
mysql> FLUSH PRIVILEGES;<br />
<br />
Now use your up arrow key to run the command<br />
<br />
mysql> SELECT Host, User, Password FROM mysql.user;<br />
<br />
and you should see that all three users now have passwords (which will be displayed in encrypted form).<br />
<br />
Then exit MySQL<br />
<br />
mysql> exit<br />
Bye<br />
$<br />
<br />
<br />
and test that all is well:<br />
<br />
$ sudo /etc/init.d/mysql restart<br />
password:<your password><br />
$ mysql -u root -p <br />
Enter Password: <mysql root password><br />
<br />
You should see<br />
<br />
Welcome to the MySQL monitor ...<br />
mysql><br />
<br />
Enter<br />
<br />
mysql> SELECT Host, User, Password FROM mysql.user;<br />
<br />
and you should see encrypted passwords for all three accounts. Note that the way MySQL is set up, you can only gain access to the <code>localhost</code> account, not to the <code>host_name</code> account but setting a password for the <code>host_name</code> account is a safer thing to do in case the set up gets changed. Now exit MySQL<br />
<br />
mysql> exit<br />
Bye<br />
$ <br />
<br />
and congratulate yourself. You are now ready for the next and hopefully easy part, installing WeBWorK.<br />
<br />
== Downloading the WeBWorK System Software and Problem Libraries ==<br />
We are finally at the point where we can start downloading and installing WeBWorK. We will use CVS to download WeBWorK. This is easy and it will also make it easy to update the system in the future. Note that the following are rather long commands; it is much easier to copy (<code>^C</code>) them from this document and paste (<code>&lt;Shift&gt; &lt;Ctrl&gt; &lt;V&gt;</code>) them in a terminal window<br />
<br />
$ cd<br />
$ cd downloads<br />
<br />
$ cvs -d :pserver:anoncvs@cvs.webwork.rochester.edu:/webwork/cvs/system checkout -r rel-2-4-dev webwork2 pg<br />
$ cvs -d :pserver:anoncvs@cvs.webwork.rochester.edu:/webwork/cvs/asu checkout database_problems<br />
<br />
The first download gives you the latest released version with patches (don't be misled by the <code>dev</code> extension --- this is not a development version).<br />
The second download contains the WeBWorK National Problem Library. This now includes the Rochester and Union Libraries along with others as sunlibraries. There is quite a bit of overlap between these libraries but now you system is loaded with many thousands of WeBWorK problems (over 13,000 in the National Problem Library main collection alone).<br />
<br />
== Installing WeBWorK ==<br />
=== Move the System into the Required Directories ===<br />
As <code>root</code> create a <code>webwork</code> directory under <code>/opt</code> and move directories there. <br />
<br />
$ su<br />
<root password><br />
# mkdir /opt/webwork<br />
# mv webwork2 /opt/webwork/<br />
# mv pg /opt/webwork/<br />
<br />
Now create the <code>courses</code> and <code>libraries</code> directories under <code>webwork</code> and copy and move content there.<br />
<br />
# mkdir /opt/webwork/courses<br />
# mkdir /opt/webwork/libraries<br />
# mv database_problems/ /opt/webwork/libraries/<br />
# cd /opt/webwork/webwork2/courses.dist<br />
# cp *.lst /opt/webwork/courses/<br />
# cp -r modelCourse/ /opt/webwork/courses/<br />
<br />
=== Setting Permissions ===<br />
<br />
The PG installation directory and files should be owned by root and not writable by other users:<br />
<br />
# cd /opt/webwork/pg<br />
# chown -R root:root .<br />
# chmod -R u+rwX,go+rX .<br />
<br />
Most WeBWorK directories and files should also be owned by root and not writable by other users:<br />
<br />
# cd /opt/webwork/webwork2<br />
# chown -R root:root .<br />
# chmod -R u+rwX,go+rX .<br />
<br />
Certain data directories need to be writable by the web server. These are <code>DATA</code>, <code>courses</code>, <code>htdocs/tmp</code>, <code>logs</code>, and <code>tmp</code>. It is convenient to give WeBWorK administrators access to these directories as well, so they can perform administrative tasks such as removing temporary files, creating and editing courses from the command line, managing logs, and so on. We will create a new group called <code>wwdata</code>, containing both the WeBWorK administrators and the web server.<br />
<br />
# Select <code>System</code>, <code>Administration</code> and then <code>Users and Groups</code><br />
# Click on <code>Unlock</code><br />
# Enter <code>&lt;your password&gt;</code> and click <code>Authenticate</code><br />
# Select <code>Manage Groups</code><br />
# Click <code>Add Group</code> <br />
# For <code>Group name</code> enter <code>wwdata</code><br />
# Under <code>Group Members</code> select yourself and click <code>OK</code><br />
# Click <code>Close</code><br />
<br />
If there are other users who will also be administering WeBWorK files,<br />
now is a good time to add them. And remember to add them to the <code>wwdata</code> group as above.<br />
<br />
Because system users are not shown by default, we can not simply use the <code>Group Manager</code> to add the Apache2 webserver (which runs as <code>www-data</code>) to the <code>wwdata</code><br />
group so we will do this by hand.<br />
<br />
# cd /etc<br />
# cp group group.bak1<br />
# gedit group<br />
<br />
<br />
# In the gedit window scroll to the last line. <br />
# It should look like <code>wwdata:x:1001:<your userid></code><br />
# Append to this line <code>,www-data</code><br />
# Then Save and Quit<br />
<br />
<br />
<br />
You can check that this succeeded in a terminal window by entering<br />
<br />
# exit<br />
$ id <your userid><br />
<br />
and then you should see <code>wwdata</code> listed under groups. Also<br />
<br />
$ id www-data<br />
<br />
should show wwdata listed under groups. Now we make the WeBWorK directories that need to be writable by the web server have <code>wwdata</code> as their group. The following are rather long commands; you might want to copy them and paste them into your terminal window rather than typing them.<br />
<br />
$ su<br />
<root password><br />
# cd /opt/webwork/webwork2/<br />
# chgrp -R wwdata DATA ../courses htdocs/tmp logs tmp<br />
# chmod -R g+w DATA ../courses htdocs/tmp logs tmp<br />
# find DATA/ ../courses/ htdocs/tmp logs/ tmp/ -type d -a ! -name CVS -exec chmod g+s {} \;<br />
# exit<br />
$<br />
<br />
== Configuring the Shell ==<br />
<br />
To make working with WeBWorK easier, there are a couple of changes you can make to your shell environment.<br />
<br />
Add the WeBWorK <code>bin</code> directory to your path. This will allow you to run WeBWorK command-line utilities without typing the full path to the utility. Goto your home directory and backup your <code>.bashrc</code> file<br />
<br />
$ cd<br />
$ cp .bashrc .bashrc.bak1<br />
<br />
Now edit <code>.bashrc</code><br />
<br />
$ gedit .bashrc<br />
<br />
After the last line add the two lines:<br />
<br />
export PATH=$PATH:/opt/webwork/webwork2/bin<br />
export WEBWORK_ROOT=/opt/webwork/webwork2<br />
<br />
Then save the file and Quit.<br />
<br />
Close your Terminal Window and open a new one so the above changes<br />
take effect. You can check that they have by<br />
<br />
$ echo $PATH<br />
$ echo $WEBWORK_ROOT<br />
<br />
== Checking Module Dependancies ==<br />
<br />
<br />
<br />
WeBWorK includes a script called <code>check_modules.pl</code> that verifies that the needed programs and Perl modules are installed on your system. Run this script to make sure you have installed the required programs and Perl modules.<br />
<br />
$ check_modules.pl apache2<br />
<br />
Scroll up and look through the listing. It should find everything except <code>PHP::Serialization</code>, <code>SOAP::Lite</code>, <code>MIME::Parser</code> and <code>XMLRPC::Lite</code> which are only required if you plan to use WeBWorK with Moodle and <code>tth</code> which is a deprecated display mode. If something is missing (flagged by <code>**</code>), look back through these instructions and/or look at 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.<br />
<br />
== Configuring WeBWorK ==<br />
<br />
=== Making Copies of the Distribution Configuration Files ===<br />
<br />
Before configuring the system, you must make local copies of the <code>global.conf</code> and <code>database.conf</code> configuration files, located in <code>/opt/webwork/webwork2/conf/</code> . Since these are owned by <code>root</code><br />
<br />
$ su<br />
<root password><br />
# cd /opt/webwork/webwork2/conf<br />
# cp global.conf.dist global.conf<br />
# cp database.conf.dist database.conf<br />
<br />
=== Global Configuration ===<br />
<br />
Most WeBWorK configuration is done in the file <code>/opt/webwork2/conf/global.conf</code>. This file provides system-wide configuration settings, and defaults for course settings. Any setting in this file can be overridden in the <code>course.conf</code> file for a particular course. To override a setting for a course, just put the new setting (using the same syntax as is in <code>global.conf</code>) in the <code>course.conf</code> file.<br />
<br />
There are several options that must be set for WeBWorK to work with your system. The rest of the file consists of customization options. Now edit <code>global.conf</code><br />
<br />
# cd /opt/webwork/webwork2/conf<br />
# gedit global.conf<br />
<br />
WeBWorK uses the DateTime module. DateTime is supposed to be able to determine the local timezone itself without you having to enter it but this often fails so it is best to just set it here. For is a list of timezones recognized by DateTime go to<br />
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 <code>DateTime::TimeZone::America::New_York</code> and you should replace <code>$siteDefaults{timezone} = "";</code> by <code>$siteDefaults{timezone} = "America/New_York";</code> <br />
<br />
# Search for <code>$siteDefaults{timezone} = "";</code> and enter your local timezone.<br />
<br />
At this point <code>TtH</code> is a deprecated display mode which we didn't install so we have to remove it from the listof possible display modes. <br />
<br />
# Search for <code>formattedText</code> and comment out the line <code>"formattedText", # format math expressions using TtH</code><br />
so it becomes<br />
<br />
# "formattedText", # format math expressions using TtH<br />
<br />
We need to set a password that WeBWorK uses when it communicates with the MySQL database. Note that this is not the same as the <code>&lt;mysql root password&gt;</code> which is the password the MySQL root user uses.<br />
# Search for <code>$database_password = "";</code> and replace this by <br /> <code>$database_password = "database_password";</code> <br />
where of course you should replace 'database_password' with your own password. Remember this password as we will need it below.<br />
<br />
WeBWorK sends mail in three instances. The PG system sends mail to report answers to questionnaires and free-response problems. The mail merge module is used to send mail to course participants, i.e. to report scores. The feedback module allows participants to send mail to course instructors.<br />
<br />
To send mail, WeBWorK needs the address of an SMTP server. Normally you will use the address of your school's SMTP server. If the local machine is running an SMTP server, use <code>localhost</code>. IMPORTANT: Our instructions above did not install an SMTP server so you will have to install and configue one if you do not use your school's SMTP server. When connecting to the SMTP server, WeBWorK must also send an email address representing the sender of the email (this has nothing to do with the <code>From</code> address on the mail message). Edit the lines<br />
$mail{smtpServer} = 'mail.yourschool.edu'; <br />
$mail{smtpSender} = 'webwork@yourserver.yourschool.edu';<br />
<br />
entering the appropriate information.<br />
<br />
If you want WeBWorK questionnaires or similar things from different courses to be mailed to a central person or persons (e.g. the WeBWorK administrator), edit the lines<br />
<br />
$mail{allowedRecipients} = [<br />
#'prof1@yourserver.yourdomain.edu',<br />
#'prof2@yourserver.yourdomain.edu',<br />
];<br />
<br />
appropriately removing the <code>#</code> and using the professor(s) actual email address(es). In order to have professors from individual courses receive such email, this <br />
should be set in course.conf to the addresses of professors of each course.<br />
<br />
Then save the file and Quit.<br />
<br />
<br />
Now become a regular user again<br />
<br />
# exit<br />
$<br />
<br />
WeBWorK uses a single database, called <code>webwork</code>, for all courses. We will create the <code>webwork</code> database now.<br />
<br />
To do this do the following (before you just copy, paste and hit <code>&lt;Enter&gt;</code> notice that you have to replace <code>database_password</code> with the password you set when editing <code>global.conf</code> above):<br />
<br />
$ mysql -u root -p mysql<br />
Enter password: <mysql root password><br />
mysql> CREATE DATABASE webwork;<br />
mysql> GRANT SELECT, INSERT, UPDATE, DELETE, CREATE, ALTER, DROP, LOCK TABLES ON webwork.* TO webworkWrite@localhost IDENTIFIED BY 'database_password';<br />
mysql> exit<br />
Bye<br />
$ <br />
<br />
where as we said replace <code>database_password</code> with the password you set when editing <code>global.conf</code> above.<br />
<br />
Since version 2.3.0 WeBWorK has an automatic database upgrade system. Rather than manually issuing SQL commands to make changes to the database, or using ad-hoc scripts like wwdb_addgw, there is a single script called <code>wwdb_upgrade</code> that applies any necessary updates. It should be run when creating a new database, and any time you upgrade WeBWorK.<br />
<br />
$ /opt/webwork/webwork2/bin/wwdb_upgrade -v<br />
<br />
=== jsMath Settings ===<br />
<br />
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 <code>webwork2/htdocs/jsMath/jsMath-fonts.tar.gz</code>, and you need to unpack this tarball before jsMath will work properly. Use the command<br />
<br />
$ su<br />
<root password><br />
# cd /opt/webwork/webwork2/htdocs/jsMath<br />
# tar vfxz jsMath-fonts.tar.gz<br />
<br />
This will unpack the archive. Since there are 20,000 tiny files, it can take a little while, so the <code>v</code> 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.<br />
<br />
<br />
== Configuring Apache ==<br />
WeBWorK ships with an Apache config file that needs to linked into your Apache configuration process. The file is named <code>webwork.apache2-config.dist</code> and located in the <code>conf</code> directory. First, copy the file to <code>webwork.apache2-config</code>:<br />
<br />
# cd /opt/webwork/webwork2/conf<br />
# cp webwork.apache2-config.dist webwork.apache2-config<br />
<br />
and now link it into your Apache configuration process<br />
<br />
# cd /etc/apache2/conf.d<br />
# ln -s /opt/webwork/webwork2/conf/webwork.apache2-config webwork.conf<br />
<br />
Then restart Apache <br />
<br />
# apache2ctl graceful<br />
# exit<br />
$<br />
<br />
== Test your configuration ==<br />
<br />
# Test the <code>/webwork2</code> location by visiting <code>http://yourserver.yourschool.edu/webwork2</code>. You should see the WeBWorK home page with no courses listed. Actually the directory <code>/opt/webwork/courses/</code> does contain the <code>modelCourse</code> but the <code>modelCourse</code> is not a real course so you will get an error message if you try to log into it. It will be used a as model for setting up other courses. For this reason <code>/opt/webwork/courses/modelCourse/</code> contains a file named <code>hide_directory</code> and so the <code>modelCourse</code> is not visible.<br />
# Test the <code>/webwork2_files</code> location by visiting <code>http://yourserver.yourschool.edu/webwork2_files</code>. You should see the "WeBWorK Placeholder Page".<br />
# You cannot test the <code>/webwork2_course_files</code> location until you have created a course.<br />
<br />
==If Something is Wrong ==<br />
If something is wrong one of the first things to check is that the config files have been edited correctly (e.g. one time a wrapped line in <code>global.conf</code> caused me problems, another time it was a missing single quote). A quick way to check this is to do a <code>diff</code> between the edited and distributed versions and check that <code>diff</code> reports the changes you made and only those.<br />
<br />
# exit<br />
$<br />
$ cd /etc/apache2/<br />
$ diff apache2.conf apache2.conf.bak1<br />
$ cd /opt/webwork/webwork2/conf/<br />
$ diff global.conf global.conf.dist<br />
$ diff database.conf database.conf.dist<br />
$ diff webwork.apache2-config webwork.apache2-config.dist <br />
<br />
If something is wrong and you fix it, you will have to restart Apache for the changes to take effect<br />
<br />
$ su<br />
<root password><br />
# apache2ctl graceful<br />
# exit<br />
$<br />
<br />
== Create the admin Course ==<br />
<br />
[[Course Administration]] gives information about creating courses. Here we will give explicit instructions for doing this.<br />
<br />
$ su<br />
<root password><br />
# newgrp wwdata<br />
# umask 2<br />
# cd /opt/webwork/courses<br />
# /opt/webwork/webwork2/bin/addcourse admin --db-layout=sql_single --users=adminClasslist.lst --professors=admin<br />
# exit<br />
# exit<br />
$<br />
<br />
Now goto <code>http://yourserver.yourschool.edu/webwork2</code> and should see the WeBWorK home page with <code>Course Adninistration</code> listed at the top. Click on it and login with Username <code>admin</code> and Password <code>admin</code> . This first thing you should do is to click on <code>Password/Email</code> and change <code>admin</code> 's password to something more secure than <code>admin</code> . <br />
<br />
Unless you choose oherwise, users with <code>professor</code> privilges in the <code>admin</code> course (i.e. WeBWorK administrators) will automatically be added to new courses with <code>professor</code> privilges and the same password as in the <code>admin</code> course. Initially the only such user is <code>admin</code> (hopefully you are not confused by the fact that the course <code>admin</code> has a user named <code>admin</code>). It's usually convenient make yourself a WeBWorK administrator. To do this (assuming you are logged in as <code>admin</code> to the <code>admin</code> course at <code>http://yourserver.yourschool.edu/webwork2/admin</code> )<br />
# Click on <code>Classlist Editor</code> in the left panel<br />
# Check <code>Add 1 student(s)</code> and click <code>Take Action!</code><br />
# Enter the appropiate information (you can leave the last three items blank) and click <code>Add Students</code><br />
# Click on <code>Classlist Editor</code> in the left panel again<br />
<br />
# When you enter a new student, by default their <code>Student ID</code> is used as their password. We'll change this now.<br />
# Select yourself with a check mark and then check <code>Give new password to Selected users</code> or just check <code>Give new password to All users</code> (as a safely mechanism you can not change the password for the user you are logged in as, currently <code>admin</code>, this way) and then click <code>Take Action!</code><br />
# Enter the password, check <code>Save changes</code> and then click <code>Take Action!</code><br />
# Finally give yourself <code>professor</code> privilges by selecting yourself with a check mark, checking <code>Edit Selected users</code> and then clicking <code>Take Action!</code> (or by just clicking on the "pencil" next to your login name which is a much faster way to edit classlist data for a single user)<br />
# Now at the far right change <code>Permission Level</code> from <code>student</code> to <code>professor</code><br />
# Check <code>Save changes</code> and then click <code>Take Action!</code><br />
<br />
At some point you will probably want to hide the <code>admin</code> course so that it is not listed on the WeBWorK home page. As we noted above the <code>modelCourse</code>, which is already hidden, is not a real course so you will get an error message if you try to log into it. This is a good reason to hide it. The <code>modelCourse</code> is very useful as a model (hence its name) for setting up other courses. The <code>admin</code> course is used for administering WeBWorK and even though regular users can not log into it (you did change the <code>admin</code> password, didn't you!!), it a little bit cleaner and safer to hide it from prying eyes. <br />
To hide a course place a file named <code>hide_directory</code> in the course directory and it will not show up in the courses list on the WeBWorK home page. It will still appear in the Course Administration listing. If you do this you will still be able to access the <code>admin</code> course using the URL <code>http://yourserver.yourschool.edu/webwork2/admin</code> but you will not see a link for it on the WeBWorK home page <code>http://yourserver.yourschool.edu/webwork2</code> . Let's hide the <code>admin</code> course.<br />
<br />
$ sudo cp /opt/webwork/courses/modelCourse/hide_directory /opt/webwork/courses/admin<br />
password:<your password><br />
<br />
<br />
Now goto <code>http://yourserver.yourschool.edu/webwork2</code> and no course will be listed.<br />
<br />
== Starting and Stoping Apache, MySQL and the GNOME desktop GUI ==<br />
If you make changes to the system, you will have to restart <code>apache2</code> before the changes take effect. On rare ocassions you may need to restart <code>MySQL</code>. <br />
=== Starting and Stoping Apache ===<br />
You have to run these commands as <code>root</code>.<br />
<br />
To start or restart (i.e. stop and then start) the <code>apache2</code> webserver run the command <br />
<br />
$ sudo apache2ctl graceful<br />
password:<your password><br />
<br />
To stop the Apache webserver run the command <br />
<br />
$ sudo apache2ctl stop<br />
password:<your password><br />
<br />
You can also start or stop apache2, listed as <code>Web server (apache2)</code>, by using the GUI interface.<br />
# Select <code>System</code>, <code>Administration</code> and then <code>Services</code><br />
# Scroll down to <code>Web server (apache2)</code><br />
# If <code>apache2</code> is running, uncheck its check box and click <code>Close</code> to stop it<br />
# If <code>apache2</code> is stopped, check its check box and click <code>Close</code> to start it<br />
<br />
Another method is to use the <code>init.d</code> script <code>apache2</code>. Run<br />
$ sudo /etc/init.d/apache2<br />
password:<your password><br />
and you will get a list of allowed commands (<code>start</code>, <code>stop</code>, <code>restart</code>, etc).<br />
<br />
Note that in an earlier version of Ubuntu I found using the GUI interface somewhat unreliable.<br />
<br />
=== Starting and Stoping MySQL ===<br />
You have to run these commands as <code>root</code>.<br />
<br />
To start the <code>MySQL</code> server run the command <br />
<br />
$ sudo /etc/init.d/mysql start<br />
password:<your password><br />
<br />
To stop the <code>MySQL</code> server run the command <br />
<br />
$ sudo /etc/init.d/mysql stop<br />
password: <your password><br />
<br />
To restart the <code>MySQL</code> server run the command <br />
<br />
$ sudo /etc/init.d/mysql restart<br />
password: <your password><br />
<br />
You can also start or stop MySQL, listed as <code>Database server (mysql)</code>, by using the GUI interface.<br />
<br />
# Select <code>Desktop</code>, <code>Administration</code> and then <code>Services</code><br />
# Scroll down to <code>Database server (mysql)</code><br />
# If <code>mysql</code> is running, uncheck its check box and click <code>Close</code> to stop it<br />
# If <code>mysql</code> is stopped, check its check box and click <code>Close</code> to start it<br />
<br />
=== Starting and stopping the GNOME desktop GUI ===<br />
<br />
The GNOME desktop is automatically started when the system boots. <br />
<br />
To stop <code>GNOME</code> so that you only have a standard terminal window run the following in a standard terminal window<br />
<br />
$ sudo /etc/init.d/gdm stop <br />
password: <your password><br />
<br />
If you stopped <code>GNOME</code> and want to restart it run the following in a standard terminal window<br />
<br />
$ sudo /etc/init.d/gdm start <br />
password: <your password><br />
<br />
==Install the WeBWorK Problem Libraries ==<br />
Before we create a real course we will install the WeBWorK Problem Libraries.<br />
<br />
===Install the National Problem Library ===<br />
The <code>National Problem Library</code> consists of both WeBWorK problems and methods for searching and selecting problems. Also it contains as sub libraries many of the other standard libraries. Normally this library is referred to as the <code>ProblemLibrary</code> but the downloaded CVS directory for it is named <code>database_problems</code>. So the first thing we do is to link <code>ProblemLibrary</code> to <code>database_problems</code>. <br />
<br />
$ cd /opt/webwork/libraries/<br />
$ sudo ln -s database_problems ProblemLibrary<br />
password: <your password><br />
<br />
Next we have to edit <code>global.conf</code>.<br />
<br />
$ cd /opt/webwork/webwork2/conf<br />
$ su<br />
Password: <root password><br />
# gedit global.conf<br />
<br />
# Search for <code>problemLibrary</code> and replace <code>$problemLibrary{root} = "";</code> by <br /> <code>$problemLibrary{root} = "/opt/webwork/libraries/ProblemLibrary";</code> <br />
<br />
Then save the file and quit. And return to a regular user<br />
<br />
#exit<br />
$<br />
<br />
We now create a database, called <code>ProblemLibrary</code>, for for the Problem Library.<br />
To do this do the following:<br />
<br />
$ mysql -u root -p mysql<br />
Enter password: &lt;mysql root password&gt;<br />
mysql> CREATE DATABASE ProblemLibrary;<br />
mysql> GRANT SELECT ON ProblemLibrary.* TO webworkWrite@localhost;<br />
mysql> exit<br />
Bye<br />
$ <br />
<br />
Update mysql<br />
<br />
$ NPL-update<br />
<br />
This has to convert a lot of data so please be patient; it can take a long time.<br />
<br />
If at some time in the future you want to upgrade the Problem Library, the process<br />
is simpler. Optionally remove the previous copy of the<br />
library, unpack the new copy in the same place, and run NPL-update.<br />
<br />
===Set up the Rochester and Union Libraries ===<br />
<br />
First we need to edit <code>global.conf</code> one last time<br />
<br />
$ cd /opt/webwork/webwork2/conf<br />
$ su<br />
Password: <root password><br />
# gedit global.conf<br />
<br />
# Search for <code>courseFiles{problibs}</code> and scroll down several lines to the line <br /> <code># rochesterLibrary =&gt; "Rochester",</code><br />
# Uncomment this line (i.e. remove the <code>#</code>) so it becomes <br /> <br />
&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp; <code>rochesterLibrary =&gt; "Rochester",</code><br />
# Directly below this line add the line <br /> <br />
&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp; <code>unionLibrary =&gt; "Union",</code><br />
# Search for <code>macrosPath</code> and scroll down several lines to the line <br /> <code>$pg{directories}{macros},</code><br />
# After this line add the line: <br /> <code>'/opt/webwork/libraries/database_problems/macros/Union',</code> <br />
<br />
Don't forget the coma (<code>,</code>) at the end of these lines. Then save the file and quit.<br />
<br />
Since we have edited <code>global.conf</code> a lot and this is a very critical file, it would be a good idea to run<br />
<br />
<br />
# exit<br />
$ diff global.conf global.conf.dist<br />
<br />
and check that you haven't made any mistakes (e.g. by introducing an inadvertant line break, etc).<br />
<br />
We next put links to the Rochester and Union Libraries in the <code>modelCourse</code> so that when we create courses copying templates from the <code>modelCourse</code>, these libraries will be available. Skip this step if you usually only want to use National Problem Library.<br />
<br />
$ cd /opt/webwork/courses/modelCourse/templates/<br />
$ sudo ln -s /opt/webwork/libraries/database_problems/Union unionLibrary<br />
password: <your password><br />
$ sudo ln -s /opt/webwork/libraries/database_problems/Rochester rochesterLibrary<br />
<br />
If you want to put another library into the <code>modelCourse</code>, just do the analogous thing. If you just want the additional library in a particular course, add the link in the <code>templates</code> directory of that course. If you look in the directory <code>/opt/webwork/libraries/database_problems/</code> you might find other libraries that are not yet listed in <code>global.conf</code> (like <code>Union</code> above) and these can be added in the same way we added <code>Union</code>. Usually they do not require additional macros like <code>Union</code> did. Finally if you add a library with non standard symbols in the name (e.g. <code>uva-statLibrary</code>) you have to use single quotes when adding it to <code>global.conf</code>, e.g. <br><br />
&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp; <code>'uva-statLibrary' => "UVA-Stat",</code> <br><br />
It's easier to just avoid such names.<br />
<br />
==Create Your First Actual Course ==<br />
<br />
Now log into the <code>admin</code> course ( <code>http://yourserver.yourschool.edu/webwork2/admin</code> ) as yourself or <code>admin</code> and <br />
# click on <code>Add Course</code><br />
# For <code>Course ID</code> enter <code>myTestCourse</code><br />
# For <code>Course Title</code> enter <code>My Test Course</code><br />
# Enter your institution<br />
# Leave <code>Add WeBWorK administrators to new course</code> checked<br />
# Add an additional instructor if you wish<br />
# Copy templates from: <code>modelCourse</code> (the default action)<br />
# Select sql_single for the database layout.<br />
# Click on <code>Add Course</code><br />
# Click <code>Log into myTestCourse</code><br />
<br />
and log in either as <code>admin</code> or yourself.<br />
<br />
At some point you will probably want to "hide" <code>myTestCourse</code> from general view but you already know how to do that.<br />
<br />
==Test that Things are Working Properly ==<br />
<br />
We will test out a few important parts of WeBWorK. If you run into problems, you should look at the Apache error log which is located at <code>/var/log/apache2/error.log</code>.<br />
<br />
Click on <code>Hmwk Sets Editor</code> on the <code>Main Menu</code>. Then select (by clicking the circle button) <code>Import</code>, select <code>setDemo.def</code> from the <code>from</code> drop down list and select <code>all current users</code> from the <code>assigning this set to</code> drop down list. Then hit <code>Take Action!</code><br />
<br />
Now click on <code>Homework Sets</code> on the <code>Main Menu</code> and click on <code>Demo</code>. Then look at the problems. Mathematical equations should be typeset. If not, edit the file <code>Constants.pm</code> in the directory <code>/opt/webwork/webwork2/lib/WeBWorK</code>. Change the line <code>$WeBWorK::PG::ImageGenerator::PreserveTempFiles = 0;</code> to <code>...::PreserveTempFiles = 1;</code>. Then restart Apache and view the first couple problems or some new ones. Then look in the directory <code>/opt/webwork/webwork2/tmp/</code>. <code>cd</code> to one of the <code>ImageGenerator.../tmp/</code> directories and look at the error and log files there. When you fix the problem remember to edit <code>...::PreserveTempFiles = 1;</code> back to 0 and restart Apache or you will be saving a lot of unnecessary files. Another useful trick is to try downloading a hard copy of an assignment and then (assuming there are errors) looking at the various log files that are linked to on the output page.<br />
<br />
When you continue looking at problems you will get an error when you try to look at Problem 6 because we have not 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 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). <br />
<br />
Next click on <code>Prob. List</code> to bring back the Problem List Page and click on <code>Download a hardcopy of this homework set</code>. The page is a little complicated because you are a professor but you can just scroll to the bottom and click on <code>Generate hardcopy for selected users and selected sets</code>. You will get an error (because of the bad Problem 6) but just click <code>Download Hardcopy</code> to get what was generated. Also you can see links to various <br />
informational files that are available if you run into problems (normally these files are removed if there are no errors).<br />
<br />
Another thing to do is to use <code>Email</code> on the <code>Main Menu</code>. Again this page is a little complicated because you can do a lot of things with it (including mail merge) but at this point just select yourself in the list to the right and hit <code>Send Email</code> at the bottom. You should receive two emails. One is the message you just sent and the other is an email with subject "WeBWorK email sent" giving information on your mailing. <br />
<br />
As a final test click on <code>Library Browser</code> on the <code>Main Menu</code>. Click <code>Problem Library </code><br />
and select a <code>Subject</code>, <code>Chapter</code> and <code>Section</code> and then hit <code>View Problems</code>. The first 20 of your selected problems will be displayed. You can also test that you can access any additional Problem Libraries that you installed.<br />
<br />
If all the above tests work, you can be pretty confident that WeBWorK is working properly.<br />
<br />
Go back to <code>Hmwk Sets Editor</code> on the <code>Main Menu</code>. Then select (by clicking the circle button) <code>Import</code>, select <code>setOrientation.def</code> from the <code>from</code> drop down list and select <code>all current users</code> from the <code>assigning this set to</code> drop down list. Then hit <code>Take Action!</code>. Then go through the Orientation problems. This is a good first set to use for introducing students to WeBWorK.<br />
<br />
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.<br />
Click on <code>Classlist Editor</code> on the <code>Main Menu</code>.<br />
Then select (by clicking the circle button) <code>Add 1 student(s)</code>and hit <code>Take Action!</code>. Add one student, say Jane Smith, with <code>Student ID</code> <code>1234</code> and <code>Login Name</code> <code>jsmith</code>.<br />
Jane Smith's initial password will be her <code>Student ID</code> <code>1234</code>. Now login as Jane Smith and play around a little.<br />
<br />
==Optional Configurations==<br />
'''Optional A''' stores WeBWorK's "temporary" files in a separate partition. <br />
'''Optional B''' installs and configures a lightweight webserver to serve static files.<br />
'''Optional C''' configures Apache so that access to WeBWorK will be through SSL.<br />
<br />
===Implement Optional A (wwtmp)===<br />
<br />
Now is the time to implement '''Optional A''' if you choose to do so. Actually you can do this at any time and your active courses will continue to function seemingly without change. The only change behind the scenes will be that temporary files will be stored in a different location.<br />
<br />
First we set the group and permissions for the <code>wwtmp</code> directory<br />
<br />
$ su<br />
<root password><br />
# cd /var/www<br />
# chgrp wwdata wwtmp<br />
# chmod ug+w wwtmp<br />
# chmod g+s wwtmp<br />
<br />
Next we have to edit <code>global.conf</code> so that WeBWorK uses the new <code>wwtmp</code> directory. Since we have a working WeBWorK system, first we make a backup copy of <code>global.conf</code>.<br />
<br />
<br />
# cd /opt/webwork/webwork2/conf<br />
# cp global.conf global.bak1<br />
# gedit global.conf<br />
<br />
Now edit <code>global.conf</code>. Find the lines <br />
<br />
$webworkDirs{htdocs_temp} = "$webworkDirs{htdocs}/tmp";<br />
$webworkURLs{htdocs_temp} = "$webworkURLs{htdocs}/tmp";<br />
and replace them by <br />
#$webworkDirs{htdocs_temp} = "$webworkDirs{htdocs}/tmp";<br />
#$webworkURLs{htdocs_temp} = "$webworkURLs{htdocs}/tmp";<br />
$webworkDirs{htdocs_temp} = '/var/www/wwtmp';<br />
$webworkURLs{htdocs_temp} = '/wwtmp';<br />
<br />
Next find the lines <br />
<br />
$courseDirs{html_temp} = "$courseDirs{html}/tmp";<br />
$courseURLs{html_temp} = "$courseURLs{html}/tmp";<br />
and replace them by <br />
#$courseDirs{html_temp} = "$courseDirs{html}/tmp";<br />
#$courseURLs{html_temp} = "$courseURLs{html}/tmp";<br />
$courseDirs{html_temp} = "/var/www/wwtmp/$courseName";<br />
$courseURLs{html_temp} = "/wwtmp/$courseName";<br />
<br />
Then save the file and quit. If you look at the <code>wwtmp</code> directory you will find it empty but after you restart apache and then access some WeBWorK problems, you will find temporary directories and files in <code>wwtmp</code>. Remember your have to restart apache for these changes to take effect.<br />
<br />
===Implement Optional B (lighttp)===<br />
<br />
As is the case for '''Optional A''' you can implement '''Optional B''' at any time and your active courses will continue to function seemingly without change. The only change behind the scenes will be that static images and pages will be served by a light weight web server.<br />
<br />
First we install the light weight webserver <code>lighttp</code><br />
<br />
# Open the <code>Synaptic Package Manager</code> (select <code>System</code>, <code>Administration</code>, <code>Synaptic Package Manager</code>). <br />
# Select <code>Search</code> <br />
# Search for <code>lighttp</code> and select it<br />
# In the pop up window <code>Mark additional required changes?</code> click <code>Mark</code> to accept the requirements.<br />
# Now click <code>Apply</code> and <code>Apply</code> again to confirm the changes.<br />
<br />
You can now quit the <code>Synaptic Package Manager</code>.<br />
<br />
Now we configure <code>lighttp</code>. First let's make a backup of the configuration file.<br />
<br />
<br />
$ su<br />
<root password><br />
# cd /etc/lighttpd<br />
# cp lighttpd.conf lighttpd.conf.bak1<br />
<br />
Now edit <code>lighttpd.conf</code>. <br />
<br />
# gedit lighttpd.conf<br />
<br />
Uncomment the line<br />
# "mod_status",<br />
so it becomes<br />
"mod_status",<br />
<br />
Search for the line<br />
server.document-root = "/var/www/"<br />
and under this line add the line<br />
alias.url = ("/webwork2_files/" => "/opt/webwork/webwork2/htdocs/")<br />
<br />
Apache2 is listening on port 80 so we set lighttp to listen on port 81. Find the line<br />
# server.port = 81<br />
and uncomment it <br />
server.port = 81<br />
<br />
Finally uncomment the line<br />
# status.status-url = "/server-status"<br />
so it becomes<br />
status.status-url = "/server-status"<br />
Then save the file and quit.<br />
<br />
Now restart lighttp<br />
<br />
$su<br />
<root password><br />
# /etc/init.d/lighttpd restart<br />
# exit<br />
$<br />
<br />
Note that you can just run <code>/etc/init.d/lighttpd</code> to get a list of all options.<br />
<br />
Now test your server by connecting to<br />
"http://localhost:81/" and/or connecting to your<br />
server from a browser on a remote machine. You should see the page '''It works!''' indicating that lighttp is running.<br />
<br />
You can check lighttp's status by connecting to<br />
"http://localhost:81/server-status" using a browser on your machine or from to "http://yourserver.yourschool.edu:81/server-status" from a browser on a remote machine.<br />
<br />
The Server-Status page doesn't indicate that lighttp is the web server, but it's certainly different than apache's Server-Status page "http://localhost/server-status".<br />
<br />
Next we configure WeBWorK to take advantage of lighttp.<br />
<br />
First let's make a backup copy of <code>global.conf</code> so that we can easily back out of these changes if necessary.<br />
<br />
# cd /opt/webwork/webwork2/conf<br />
# cp global.conf global.bak2<br />
<br />
<br />
Now edit <code>global.conf</code>. Note that while '''Optional B''' is independent of '''Optional A''', we assume most people implementing '''Optional B''' will have already implemented '''Optional A'''. Therefore we give instructions for editing <br />
global.conf assuming that '''Optional A''' has been implemented. If this is not the case, modify the instructions below accordingly. Also replace <code>yourserver.yourschool.edu</code> with the correct address.<br />
<br />
# gedit global.conf<br />
<br />
Find the line<br />
$webwork_htdocs_url = "/webwork2_files";<br />
and replace it by<br />
#$webwork_htdocs_url = "/webwork2_files";<br />
$webwork_htdocs_url = 'http://yourserver.yourschool.edu:81/webwork2_files';<br />
<br />
Find the line<br />
$webworkURLs{htdocs_temp} = '/wwtmp'<br />
and replace it by<br />
#$webworkURLs{htdocs_temp} = '/wwtmp';<br />
$webworkURLs{htdocs_temp} = 'http://yourserver.yourschool.edu:81/wwtmp';<br />
<br />
Find the line<br />
$courseURLs{html_temp} = "/wwtmp/$courseName";<br />
and replace it by<br />
#$courseURLs{html_temp} = "/wwtmp/$courseName";<br />
$courseURLs{html_temp} = "http://yourserver.yourschool.edu:81/wwtmp/$courseName";<br />
<br />
Then save the file and quit.<br />
<br />
Now restart apache and lighttp.<br />
<br />
$ sudo apache2ctl graceful<br />
password:<your password><br />
$ sudo /etc/init.d/lighttpd restart<br />
<br />
To test things go to your test course <code>http://yourserver.yourschool.edu/webwork2/myTestCourse/</code>. Before you login right click on the WeBWorK icon in the upper left hand corner of the login page. The click on Properties (or whatever is appropriate on your browser) and check that the image is being served from port 81 (something like <code>http://yourserver.yourschool.edu:81/webwork2_files/images/webwork_rectangle.png</code>. Then log into your course and view a problem with typeset equations (e.g. Problem 1 of the Demo set). Again right click on the typeset equation and check that the image is being served from port 81.<br />
<br />
===Implement Optional C (SSL)===<br />
'''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.<br />
<br />
I cribbed these directions from several sources, the main one being http://www.akadia.com/services/ssh_test_certificate.html.<br />
<br />
We will create and work in a <code>tmp</code> directory.<br />
<br />
$ cd<br />
$ mkdir tmp<br />
$ cd tmp<br />
<br />
First we create an RSA Private Key.<br />
<br />
$openssl genrsa -des3 -out server.key 1024<br />
<br />
When you are asked for a <code>pass phrase</code>, enter a phrase which we refer to as <code>&lt;my pass phrase&gt;</code> and then confirm it. Next generate a Certificate Signing Request<br />
openssl req -new -key server.key -out server.csr<br />
<br />
Enter the requested information. '''Important:''' when you are prompted for the <code>Common Name</code> enter your server's fully qualified domain name, something like <code>yourserver.yourschool.edu</code>. You can leave the last two items <br />
A challenge password []:<br />
An optional company name []:<br />
blank.<br />
<br />
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.<br />
<br />
$ cp server.key server.key.bak1<br />
$ openssl rsa -in server.key.bak1 -out server.key<br />
<br />
Next we generate a self-signed certificate which is good for 365 days<br />
<br />
$ openssl x509 -req -days 365 -in server.csr -signkey server.key -out server.crt<br />
<br />
Now we become root, move these files, and set their group and permission.<br />
<br />
$ su<br />
<root password><br />
# mv server.crt /etc/ssl/private<br />
# mv server.key /etc/ssl/private<br />
# cd /etc/ssl/private<br />
# chgrp ssl-cert server.*<br />
# chmod 640 server.*<br />
<br />
Next we enable the <code>mod_ssl</code> module<br />
# a2enmod ssl<br />
<br />
Now we have to configure Apache to use SSL.<br />
# cd /etc/apache2/sites-enabled/<br />
# cp default default.bak1<br />
# gedit default<br />
<br />
Replace the first line<br />
NameVirtualHost *<br />
by the two lines<br />
NameVirtualHost *:80<br />
NameVirtualHost *:443<br />
Now edit the next non blank line<br />
<VirtualHost *><br />
changing it to<br />
<VirtualHost *:80><br />
Next copy the entire section <br />
<VirtualHost *:80> <br />
...<br />
</VirtualHost><br />
(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.<br />
Edit the new second<br />
<VirtualHost *:80><br />
changing it to<br />
<VirtualHost *:443><br />
Now at the end of the file just above the line<br />
</VirtualHost><br />
add the three lines<br />
SSLEngine on<br />
SSLCertificateFile /etc/ssl/private/server.crt<br />
SSLCertificateKeyFile /etc/ssl/private/server.key<br />
Then save the file and quit.<br />
Finally we restart Apache<br />
# apache2ctl graceful<br />
and test things. Connect to https://yourserver.yourschool.edu/webwork2/mtTestCourse<br />
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). <br />
<br />
Assuming that everything is working, the last thing we do is set things up so that requests to http://yourserver.yourschool.edu/webwork2/ are automatically redirected to https://yourserver.yourschool.edu/webwork2/.<br />
<br />
# gedit default<br />
<br />
In the <br />
<VirtualHost *:80><br />
section just above the line<br />
ScriptAlias /cgi-bin/ /usr/lib/cgi-bin/<br />
add the line<br />
Redirect permanent /webwork2 https://yourserver.yourschool.edu/webwork2<br />
where of course you should edit <code>yourserver.yourschool.edu</code> appropriately.<br />
Then save the file and quit.<br />
Restart Apache<br />
# apache2ctl graceful<br />
and try connecting to http://yourserver.yourschool.edu/webwork2/. The real connection should be through https://yourserver.yourschool.edu/webwork2/.<br />
<br />
==Where to go From Here ==<br />
<br />
You should play around with <code>myTestCourse</code> e.g. click on <code>Library Browser</code> and browse the <code>Problem Library</code> and also the <code>Rochester</code> and <code>Union</code> libraries.<br />
<br />
Look at http://webhost.math.rochester.edu/webworkdocs/docs/courseadmin/usingwebwork<br />
<br />
Read [[Course Administration]] for more information about creating courses.<br />
<br />
Consult [[Category:Administrators]] for other WeBWorK documentation for system administrators.<br />
<br />
-- Main.ArnoldPizer - 15 May 2008 <br /><br />
<br />
[[Category:Installation Manuals]]</div>Xiong Chiamiovhttps://webwork.maa.org/mediawiki_new/index.php?title=Installation_Manual_for_2.4_on_Ubuntu_8.04&diff=3265Installation Manual for 2.4 on Ubuntu 8.042008-07-03T15:19:50Z<p>Xiong Chiamiov: /* Ubuntu Software Packages */ add aptitude command for easy copy+paste</p>
<hr />
<div>These instructions cover the installation of the Ubuntu Linux 8.04 operating system and WeBWorK 2.4 from scratch. <br />
<br />
They 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.<br />
<br />
== Notation ==<br />
<br />
First some short comments on notation we will be using. We will use <code>&lt;key&gt;</code> to indicate that you should press a specific key (e.g. <code>&lt;Enter&gt;</code>, <code>&lt;Tab&gt;</code>, <code>&lt;F12&gt;</code>, etc.). Sometimes we will also use e.g. <code>&lt;root password&gt;</code> to indicate you have to enter the root password.<br />
<br />
<code>^</code> will indicate the <code>&lt;Ctrl&gt;</code> key so e.g. <code>^X</code> is really shorthand for <code>&lt;Ctrl&gt; &lt;X&gt;</code>, i.e. press the Ctrl key and hit the X key.<br />
<br />
We will give references to specific versions of software, e.g. httpd-2.2.4.tar.gz rather than the more general httpd-2.x.x.tar.gz. In most cases you should be able to use the latest stable version but we have only tested the versions listed.<br />
<br />
== Installing the Ubuntu 8.04 Linux Operating System ==<br />
<br />
===Installation CD ===<br />
Obtain the <code>Desktop Edition, Alternate</code> installation DVD/CD set. Connect to http://www.ubuntu.com/ for information. On the download page http://www.ubuntu.com/getubuntu/download make sure you check the box for <code>Check here if you need the alternate desktop CD. This CD does not include the Live CD, instead it uses a text-based installer</code>. For example you can use wxDownload Fast or BitTorrent to download an ISO image of the installation CD and then burn your own installation CD. 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/7.04/MD5SUMS). wxDownload Fast automatically calculates the MD5 checksums which is convenient. I have had good luck downloading from mirrors.kernel.org but your experience may differ. These instructions will assume you have the installation CD but installing from a commercial DVD/CD set or from the net should be essentially identical.<br />
<br />
Place the installation CD in your DVD/CD drive and reboot your computer from the DVD drive. You may have to press <code>&lt;F12&gt;</code> 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.<br />
<br />
First select <code>English</code> by just hitting <code>&lt;Enter&gt;</code>.<br />
<br />
You will see a list of options. <br />
<br />
# If you want hit <code>&lt;F1&gt;</code> to obtain help and see additional boot methods<br />
# You can just hit <code>&lt;Enter&gt;</code> to accept the default install method except in the following situation<br />
# If your network has DHCP enabled but you want to setup your server with a static IP address, then hit <code>&lt;F6&gt;</code> and on the <code>Boot OPtions</code> line move the cursor before <code>quiet --</code> and type <code>netcfg/disable_dhcp=true</code> , leave a space before <code>quiet</code> and then hit <code>&lt;Enter&gt;</code><br />
# A succession of pages follow, for each select the obvious option and hit <code>&lt;Enter&gt;</code>. For example my obvious options are <code>English</code>, <code>United States</code>, <code>&lt;No&gt;</code>, <code>USA</code> and <code>USA</code> <br />
# The system will than scan your CD and load various components<br />
# If your system has multiple network interfaces, you will be asked to select the one to be used during the installation (which will usually be a hard wired ethernet connection)<br />
# Unless you entered the <code>netcfg/disable_dhcp=true</code> boot option above, the system will try to configure your network using DHCP. If you have DHCP, your network interface will be set up automatically. If you don't have DHCP, automatic network configuration will fail quickly (or just hit <code>&lt;Enter&gt;</code> to <code>Cancel</code> if you are impatient). Then hit <code>&lt;Enter&gt;</code> to <code>Continue</code><br />
<br />
'''Manual network configuration'''. If your network interface was set up automatically by DHCP, you can skip the rest of this paragraph. Otherwise you will have to enter your machine's static ip address, etc. To do this<br />
# Select <code>Configure network manually</code><br />
# Enter your computer's IP address and use <code>&lt;Tab&gt;</code> to select <code>Continue</code><br />
# The <code>netask</code> is probably OK as it but another possibility may be 255.255.0.0<br />
# Enter the ip address of your gateway router. Ubuntu makes a good guess at this, but your network may be set up differently.<br />
# Next enter the ip address(es) of up to 3 nameservers separated by spaces (at a minimum you have to enter the ip address one nameserver)<br />
# Enter the name of your server<br />
# Enter the domain name for the domain your server sits on (e.g. math.myschool.edu)<br />
# This completes the static ip address setup<br />
<br />
Now select your time zone and wait for the clock to be configured<br />
<br />
===Optional Configurations===<br />
<br />
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.<br />
<br />
'''Optional A''' creates a separate partition 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 means that it is easier and faster to back up other partitions and skip backing up unnecessary files.<br />
<br />
'''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.<br />
<br />
'''Optional C''' configures Apache so that access to WeBWorK will be through an encrypted Secure Sockets Layer (SSL) with an https: URL.<br />
<br />
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.<br />
<br />
===Partition disks===<br />
Next comes the <code>Partition disks</code> 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. <br />
<br />
'''Optional A''': The default partitioning scheme creates just two partitions, a root (<code>/</code>) partition and a swap partition. Here we will create those and an additional partition for WeBWorK's temporary files.<br />
<br />
# On the <code>Partition disks</code> page use <code>&lt;Tab&gt;</code> to select <code>Go Back</code> and then select <code>Partition disks</code> <br />
# Use the down arrow to select your disk (<code>sda</code>)<br />
# On the <code>You have selected an entire device to partition...</code> page select <code>Yes</code> to the question <code>Create new empty partition table on this device</code><br />
# On the <code>This is an overview...</code> page select <code>FREE SPACE</code><br />
# On the <code>How to use this free space</code> page select <code>Create a new partition</code><br />
# 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 (<code>/</code>) partition. Actually if you are going through the trouble of doing this, you probably will want to research other partitioning recommendations.<br />
# On the <code>The maximum size you can use...</code> page enter the size for your root (<code>/</code>) partition and <code>Continue</code><br />
# Select <code>Primary</code> for the type of the new partition<br />
# Select <code>Beginning</code> for the location of the new partition<br />
# Select <code>/</code> for the Mount point of the new partition and then select <code>Done setting up the partition</code><br />
<br />
Now we repeat the process for the partition which will hold WeBWorK's temporary files.<br />
# On the <code>This is an overview...</code> page select <code>FREE SPACE</code><br />
# On the <code>How to use this free space</code> page select <code>Create a new partition</code><br />
# On the <code>The maximum size you can use...</code> page enter the size for WeBWorK's temporary files partition. As we said 25 GB for every 1,000 students should be ample. Then <code>Continue</code><br />
# Select <code>Logical</code> for the type of the new partition<br />
# Select <code>Beginning</code> for the location of the new partition<br />
# Select <code>Mount point</code> and then hit <code>&lt;Enter&gt;</code><br />
# Select <code>Enter manually</code> and then hit <code>&lt;Enter&gt;</code><br />
# For the <code>Mount point for this partition</code> enter <code>/var/www/wwtmp</code> and <code>Continue</code><br />
# Then select <code>Done setting up the partition</code><br />
<br />
Finally we set up the swap partition<br />
# On the <code>This is an overview...</code> page select <code>FREE SPACE</code><br />
# On the <code>How to use this free space</code> page select <code>Create a new partition</code><br />
# On the <code>The maximum size you can use...</code> 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 <code>Continue</code><br />
# Select <code>Logical</code> for the type of the new partition<br />
# Select <code>Beginning</code> for the location of the new partition<br />
# Select <code>Use as</code> and then hit <code>&lt;Enter&gt;</code><br />
# Select <code>swap area</code> and then hit <code>&lt;Enter&gt;</code><br />
# Then select <code>Done setting up the partition</code><br />
<br />
Finally <br />
# Review your changes and<br />
# Select <code>Finish partitioning and write changes to disk</code> and then hit <code>&lt;Enter&gt;</code><br />
# Select <code>Yes</code> to confirm the changes<br />
<br />
===Base Installation===<br />
# Now the base installation takes place --- this takes a short time<br />
# Enter yourself as a user (with user name and password). Note this account will function partially as the <code>root</code> account so you might want to pick a different username and password than you regularly use. <br />
# You can probably leave the HTTP proxy information blank<br />
# Now sit back and relax while a lot of software is installed --- this takes awhile<br />
<br />
The final step is to install the boot loader. I have a non standard setup and for some reason I had trouble installing the Grub boot loader but Lilo worked fine. Almost certainly, Grub will work fine for you<br />
<br />
===Continue Installation ===<br />
After this finishes the system will eject the CD and ask you to reboot. <br />
<br />
# Log into your account <br />
# Accept any available updates. You may see a little notification icon (it has a arrow on it) to the right of your name in the upper right hand corner of the screen --- click on it. Alternately you can select <code>System</code>, <code>Administration</code>, <code>Update Manager</code>. Click <code>install Updates</code>. You may have to enter the <code>&lt;your password&gt;</code> which functions as the <code>&lt;root password&gt;</code> . Follow any instructions, e.g. you may be told to reboot as soon as the installation is completed (to reboot, select <code>System</code>, <code>Quit</code> and then <code>Restart</code>)<br />
<br />
===Test Browser and Keyboard ===<br />
<br />
After reboot and login, click on <code>Applications</code>, <code>Internet</code>, <code>Firefox Web Browser</code> (or just click the Firefox icon at the top of the screen) and you should be connected to the world. <br />
Goto <br />
http://webwork.maa.org/wiki/Installation_Manual_for_2.4_on_Ubuntu_8.04<br />
where you can view this document and, if you want, copy commands that you need (see below).<br />
<br />
If something is wrong and you are not connected to the web, the first thing to do is check that you entered the correct network information.<br />
# Select <code>System</code>, <code>Administration</code>, <code>Network</code><br />
# Click on <code>Unlock</code><br />
# Enter <code>&lt;your password&gt;</code> and click <code>Authenticate</code><br />
# Select <code>Wired connection</code> and click <code>Properties</code><br />
# Check that all the entries are correct and edit them if they are not<br />
# Then click <code>OK</code><br />
# Next click on <code>DNS</code> and check the name server entries and correct if necessary<br />
# Click on <code>Close</code> to close <code>Network settings</code><br />
Your network connection should start up almost immediately. If you are still having problems it's time to investigate further or seek help.<br />
<br />
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. Click <code>System</code>, <code>Preferences</code>, <code>Keyboard</code> and then increase the delay time interval and hit <code>Close</code>.<br />
<br />
== Terminal Window Notation and Use ==<br />
<br />
Before installing and configuring additional software, we need to talk about terminal windows.<br />
<br />
To open a terminal window click <code>Applications</code>, <code>Accessories</code> and then select <code>Terminal</code>.<br />
<br />
In a terminal window some commands will have to be run as root whereas<br />
others should be run as a regular user. We will use # to indicate<br />
that the command is to be run as root e.g.<br />
<br />
# perl -MCPAN -e shell<br />
<br />
and $ to indicate that the command is to be run as a normal user e.g.<br />
<br />
$ cp .bashrc .bashrc.bak1<br />
<br />
To execute the above commands you have to hit <code>&lt;Enter&gt;</code>. We'll just assume this. <br />
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.<br />
<br />
The bash shell which you will be using has a number of very<br />
convenient features.<br />
<br />
One is command and file name completion. If you are typing (e.g.<br />
<code>ch</code>) and hit <code>&lt;tab&gt;</code> bash will complete the command or filename if it is<br />
unambiguous (or more precisely it will complete as much as possible).<br />
If there are multiple possibilities (as in the case of <code>ch</code>) nothing will<br />
happen (except you may hear a beep) and you can type more letter(s) and hit <code>&lt;tab&gt;</code> again. Or you can<br />
hit <code>&lt;tab&gt;</code> a second time and you will see a list of all possible<br />
completions. E.g. entering <code>ch&lt;tab&gt;&lt;tab&gt;</code> gives a list of possible<br />
completions and <code>ch&lt;tab&gt;g&lt;tab&gt;</code> (or <code>chg&lt;tab&gt;</code>) gives <code>chgrp</code>, the change group command. This<br />
is very fast and convenient and it also leads to fewer typing errors.<br />
<br />
Another useful shortcut is the command history. Using the up and down<br />
arrow keys will bring up previous commands which can be edited and then<br />
executed. If you are repeating a command or entering a command which<br />
is similar to a previous one, this is very useful.<br />
<br />
You can copy commands from these instructions (with <code>copy</code> from the Edit dropdown list or <code>^C</code>) and paste them into a terminal window<br />
(with <code>paste</code> from the Edit dropdown list or <code>&lt;Shift&gt; &lt;Ctrl&gt; &lt;V&gt;</code>). However typing yourself using command completion is probably just as fast except if a command is long.<br />
<br />
By default Ubuntu has no password set for the root user. To gain root access you have to type in your own user password. This is the password you set for the first user while installing Ubuntu. However we will<br />
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:<br />
<br />
$ sudo passwd<br />
Password: <your password><br />
<br />
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'''.<br />
<br />
Enter new UNIX password: <root password><br />
Retype new UNIX password: <root password><br />
passwd: Password updated successfully<br />
$<br />
<br />
To test this <br />
<br />
$ su<br />
Password: <root password><br />
# whoami<br />
root<br />
#exit<br />
$<br />
<br />
Finally perhaps a safer way to run commands as <code>root</code> is to use the <code>sudo</code> command<br />
<br />
$ sudo <command><br />
Password: <your password><br />
<br />
After you enter the password the command is executed. For a certain period (maybe 5 minutes) you can execute additional <code>sudo</code> commands without reentering <code>&lt;your password&gt;</code>. A log of all <code>sudo</code> commands is kept (I don't know where). In these instructions for the most part we will not use <code>sudo</code>, but keep it in mind for other times that you have to become <code>root</code> in order to execute a few commands (e.g. restarting <code>Apache</code>).<br />
<br />
Note that for certain GUI tools such as the <code>Synaptic Package Manager</code> that require root access, the password required is <code>&lt;your password&gt;</code>, the password for the first account you set up, not the new <code>&lt;root password&gt;</code>.<br />
<br />
For our next terminal window task create a <code>downloads</code> directory where we will keep copies of downloaded software.<br />
<br />
$ cd<br />
$ mkdir downloads<br />
<br />
==Ubuntu Software Packages ==<br />
<br />
Our next task is to install a number of Ubuntu software packages.<br />
<br />
# Select <code>System</code>, <code>Administration</code> and then <code>Synaptic Package Manager</code>. You will have to enter the <code>&lt;your password&gt;</code>. The <code>Synaptic Package Manager</code> window will open<br />
# Click on <code>Reload</code> to bring the package information up to date<br />
<br />
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 <code>libnet-ldap-perl</code> and then just give the list of required packages.<br />
<br />
# Select <code>Search</code> <br />
# Under <code>Look in:</code> select <code>Name</code>. The default <code>Description and Name</code> sometimes returns too many possibilities<br />
# We are searching for <code>libnet-ldap-perl</code> so enter <code>ldap-perl</code> (or something similar; you can copy and paste from this document if you want) and click on <code>Search</code><br />
# This should result in 3 possibilities. Select and Mark for Installation (by double clicking or checking and then selecting <code>Mark for Installation</code>) <code>libnet-ldap-perl</code>. You will see a pop up window <code>Mark additional required changes?</code> and you should always click <code>Mark</code> to accept the requirements.<br />
# Follow this basic procedure for all the packages listed below<br />
<br />
Here is the list of Debian packages that need to be installed. See [[Installation Manual for 2.4]] for a short explanation of what most of these packages do. <br />
<br />
# <code>apache2</code><br />
# <code>apache2-mpm-prefork</code><br />
# <code>cvs</code><br />
# <code>dvipng</code><br />
# <code>libapache2-request-perl</code><br />
# <code>libdatetime-perl</code><br />
# <code>libdbd-mysql-perl</code><br />
# <code>libemail-address-perl</code><br />
# <code>libextutils-xsbuilder-perl</code><br />
# <code>libgd-gd2-perl</code><br />
# <code>libmail-sender-perl</code><br />
# <code>libnet-ldap-perl</code><br />
# <code>libossp-uuid-perl</code><br />
# <code>libsql-abstract-perl</code><br />
# <code>libstring-shellquote-perl</code><br />
# <code>libtimedate-perl</code><br />
# <code>libxml-parser-perl</code><br />
# <code>libxml-writer-perl</code><br />
# <code>mysql-server-5.0</code><br />
# <code>netpbm</code><br />
# <code>openssh-server</code><br />
# <code>preview-latex-style</code><br />
# <code>tetex-bin</code><br />
# <code>tetex-extra</code><br />
<br />
When I do this I see on the bottom of <code>Synaptic Package Manager</code> window <code>82 to install/upgrade</code>, <code>1 to remove</code>. Your numbers may differ slightly. <br />
Now click <code>Apply</code> and <code>Apply</code> again to confirm the changes. You will be asked several times to enter a<br />
<code>New password for the MySQL "root" user</code>; just hit <code>&lt;Enter&gt;</code> which gives the default blank password. We will fix this and several other MySQL security issues below.<br />
<br />
That completes the set up of your base Ubuntu system. You can quit the <code>Synaptic Package Manager</code>.<br />
<br />
If you would prefer to install all of these packages in one fell swoop, run this command as root:<br />
<code># aptitude install apache2 apache2-mpm-prefork cvs dvipng libapache2-request-perl libdatetime-perl libdbd-mysql-perl libemail-address-perl libextutils-xsbuilder-perl libgd-gd2-perl libnet-ldap-perl libossp-uuid-perl libsql-abstract-perl libnet-ldap-perl libsql-abstract-perl libstring-shellquote-perl libtimedate-perl libxml-parser-perl libxml-writer-perl mysql-server-5.0 netpbm openssh-server preview-latex-style tetex-bin tetex-extra</code><br />
<br />
== Installing Perl Modules ==<br />
We now have to install several additional Perl modules which unfortunately are not available from the Debian package system.<br />
<br />
=== Testing Perl Modules ===<br />
To test if a Perl module is installed and working on your system, issue the following command, replacing <code>Module</code> with the name of the module:<br />
<br />
$ perl -MModule -e 'print "installed!\n"'<br />
<br />
If the module is installed you will see <code>installed!</code>. If not you will see at lot of gibberish. E.g. at this stage in our installation process <code>CPAN</code> is installed and <code>MXML::Parser::EasyTree</code> is not so<br />
<br />
$ perl -MCPAN -e 'print "installed!\n"'<br />
<br />
yields<br />
<br />
installed!<br />
<br />
and<br />
<br />
$ perl -MXML::Parser::EasyTree -e 'print "installed!\n"'<br />
<br />
yields<br />
<br />
Can't locate XML/Parser/EasyTree.pm in @INC (@INC contains: <br />
/etc/perl /usr/local/lib/perl/5.8.8 /usr/local/share/perl/5.8.8<br />
...<br />
<br />
=== Installing Additional Perl Modules from CPAN ===<br />
<br />
Be aware that in rare cases you might have to <br />
as root run<br />
<br />
$ su<br />
<root password><br />
# unset LANG<br />
# exit<br />
$<br />
<br />
since otherwise the installation of some modules (Module::Build is an example) may fail.<br />
<br />
First we will set up CPAN. For this you have to be root.<br />
<br />
$ su<br />
<root password><br />
# perl -MCPAN -e shell<br />
<br />
Since this is the first time you are using CPAN it will ask you <code>Are you ready for manual configuration?</code> <br />
Respond <code>no</code> and that should be it. <br />
<br />
Next we add at least one mirror and reload the index. A list of mirrors can be found at http://mirrors.cpan.org. To add the mirror ftp://mirrors.kernel.org/pub/CPAN and reload the index do the following. For me, a slow and inaccurate typist, copying (<code>^C</code>) and pasting (<code>&lt;Shift&gt; &lt;Ctrl&gt; &lt;V&gt;</code>) is much faster.<br />
<br />
cpan> o conf urllist push ftp://mirrors.kernel.org/pub/CPAN<br />
cpan> reload index<br />
<br />
Note that one time this failed when I tried to do it in the evening but when I tried again the next morning it worked fine. Now we update CPAN itself<br />
<br />
cpan> install Bundle::CPAN<br />
<br />
and always hit <code>&lt;Enter&gt;</code> to accept the defaults when prompted. This can be a long process with many long pauses. Please be patient. <br />
When you again see the <br />
<br />
cpan><br />
<br />
prompt enter<br />
<br />
cpan> reload cpan<br />
cpan> o conf commit<br />
<br />
Now install the following modules<br />
<br />
cpan> install XML::Parser::EasyTree Iterator Iterator::Util Net::IP <br />
<br />
and in case you are prompted accept all defaults by just hitting <code>&lt;Enter&gt;</code>. <br />
Note that with more than one module to install, we just list them after <code>install</code> separated by spaces.<br />
<br />
When you again see the <br />
<br />
cpan><br />
<br />
prompt enter<br />
<br />
cpan> exit<br />
#<br />
<br />
=== Installing Additional Perl Modules from Source ===<br />
At one point in time (August 2006), the installation of <code>DateTime</code> using CPAN was broken. Currently <code>DateTime</code> 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. <br />
<br />
'''IMPORTANT:''' With Debian we have already installed <code>DateTime</code> 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.<br />
<br />
Now we give the example of installing <code>DateTime</code> from source. As we said you can skip this part.<br />
<br />
Goto http://search.cpan.org/,<br />
search for <code>DateTime</code> and click on <code>DateTime</code>. Then near the top right download <code>DateTime-0.36.tar.gz</code> and save it to disk. Move it to your <code>downloads</code> directory. Then<br />
<br />
$ cd <br />
$ cd downloads<br />
$ tar -zvxf DateTime-0.36.tar.gz<br />
$ cd DateTime-0.36/<br />
<br />
<br />
$ perl Makefile.PL<br />
$ make<br />
$ make test<br />
<br />
If <code>make test</code> indicates something is missing you will have to install that. In fact in the case of <code>DateTime</code>, you would see that quite a few things are missing.<br />
<code>DateTime</code> requires the additional modules <code>version</code> , <code>Module::Build</code> , <code>Class::Singleton</code> , <code>DateTime::TimeZone</code> and <code>DateTime::Locale</code> . We could install these using CPAN<br />
<br />
# perl -MCPAN -e shell<br />
cpan> install version Module::Build Class::Singleton DateTime::TimeZone DateTime::Locale<br />
cpan> exit<br />
# exit<br />
$<br />
<br />
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<br />
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 <code>package/file.pm</code> was not found, you should serach for and install <code>package::file</code> since perl modules use a double colon (<code>::</code>) as a directory separator.<br />
<br />
Assuming all is OK<br />
<br />
$su<br />
<root password><br />
# make install<br />
# exit<br />
$<br />
<br />
Finally you should definitely test that the module (e.g. <code>DateTime</code>) was installed sucessfully<br />
<br />
$ perl -MDateTime -e 'print "installed!\n"'<br />
<br />
If you see <br />
<br />
installed!<br />
<br />
you can celebrate.<br />
<br />
== Apache 2 and mod_perl ==<br />
<br />
First we have to enable a couple Apache modules. Acting as <code>root</code> in a terminal window enter<br />
<br />
# a2enmod apreq<br />
# a2enmod info<br />
<br />
Next we make a copy of the configuration files for safekeeping. <br />
<br />
# cd /etc/apache2/mods-available<br />
# cp info.conf info.conf.bak1<br />
# cp status.conf status.conf.bak1<br />
<br />
Now we will edit configuration files <code>info.conf</code> and <code>status.conf</code> to allow us to view information about the setup and performance of the web server. Note that this is not absolutely necessary but it can be very useful. You can use your favorite editor but we will give instructions assuming you are using <code>gedit</code>. Note that you have to be root to edit these files. First we edit <code>info.conf</code><br />
<br />
# cd /etc/apache2/mods-available<br />
# gedit info.conf<br />
<br />
I suggest you allow access to server information from e.g. your department domain. To do this uncomment (i.e. remove the <code>#</code> from) <br />
# Allow from .example.com<br />
and then replace <code>.example.com</code> by <code>.math.yourschool.edu</code><br />
where of course you should edit <code>.math.yourschool.edu</code> appropriately. <br />
<br />
Then save the file and quit (<code>Save</code> and <code>File</code>, <code>Quit</code>).<br />
<br />
Now we edit <code>status.conf</code><br />
<br />
# cd /etc/apache2/mods-available<br />
# gedit status.conf<br />
<br />
After the comments at the top and above the <code><Location /server-status></code> line enter<br />
<br />
ExtendedStatus On<br />
<br />
Now edit the <br />
# Allow from .example.com<br />
line just as you did for <code>info.conf</code>.<br />
Then save the file and quit<br />
<br />
Now we have to set your server's fully qualified domain name. <br />
# Select <code>System</code>, <code>Administration</code>, <code>Network</code><br />
# Click on <code>Unlock</code><br />
# Enter <code>&lt;your password&gt;</code> and click <code>Authenticate</code><br />
# Click on <code>General</code><br />
# Under <code>Host name</code> enter <code>your_server_name</code> (if it's not already there)<br />
# Then under <code>Domain name</code> enter your server's domain name, something like <code>department.school.edu</code><br />
<br />
Next<br />
# Click on <code>Hosts</code><br />
#There should also be an entry with your server's IP address (if not you should add one)<br />
# Select the entry with your server's IP address and click <code>Properties</code><br />
# Under Aliases you should see your server's fully qualified domain name, something like <code>your_server_name.department.school.edu</code><br />
# Add or edit these entries if they are not correct<br />
# Then click <code>OK</code><br />
# And click <code>Close</code> to close <code>Network settings</code><br />
<br />
You can check these settings by running the commands<br />
<br />
$ hostname --fqdn<br />
<br />
and <br />
<br />
$ hostname<br />
<br />
The first respond with the fully qualified domain name and the second with just <code>your_server_name</code>.<br />
<br />
If the command <code>hostname --fqdn</code> returns <code>Unknown host</code> do the following:<br />
<br />
# Select <code>System</code>, <code>Administration</code>, <code>Network</code><br />
# Click on <code>Unlock</code><br />
# Enter <code>&lt;your password&gt;</code> and click <code>Authenticate</code><br />
# Click on <code>Hosts</code><br />
# Select the entry with your server's IP address and click <code>Properties</code><br />
# Under Aliases you should see your server's fully qualified domain name, something like <code>your_server_name.department.school.edu</code><br />
# Select the entry <code>127.0.0.1</code> and click <code>Properties</code><br />
# Under Aliases make sure you have the following entries in order<br />
## first your server's fully qualified domain name, something like <code>your_server_name.department.school.edu</code><br />
## second your server's name, something like <code>your_server_name</code><br />
## third <code>localhost</code><br />
# Click <code>Add</code> and add an entry with <code>IP address</code> <code>127.0.1.1</code> and under <code>Aliases</code> put your server's fully qualified domain name, something like <code>your_server_name.department.school.edu</code><br />
# Then click <code>OK</code><br />
# And click <code>Close</code> to close <code>Network settings</code><br />
<br />
Then check again by running the commands<br />
<br />
$ hostname --fqdn<br />
<br />
and <br />
<br />
$ hostname<br />
<br />
Note that if your server can not find its fully qualified domain name, certain tools (such as the Synaptic Package Manager) will not start.<br />
<br />
Now restart Apache<br />
<br />
$su<br />
<root password><br />
# apache2ctl graceful<br />
# exit<br />
$<br />
<br />
and test your server by connecting to<br />
"http://localhost/" and/or connecting to your<br />
server from a browser on a remote machine. You should see the page '''It works!''' indicating that Apache is running.<br />
<br />
You can check Apache's status by connecting to<br />
"http://localhost/server-status" using a browser on your machine or from a browser on a remote machine in the math.yourschool.edu domain.<br />
<br />
Further test Apache by connecting to<br />
"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 <br />
information about Apache. In particular under <code>Server Settings</code> you should see<br />
<br />
Server Version: Apache/2.2.8 (Ubuntu) mod_apreq2-20051231/2.6.0 mod_perl/2.0.3 Perl/v5.8.8<br />
<br />
indicating that both <code>mod_apreq2</code> and <code>mod_perl</code> are installed.<br />
<br />
If you have problems now or in the future, a good first thing to do is to look at the Apache error log which is located at <code>/var/log/apache2/error.log</code>. In the directory <code>/var/log/apache2/</code> you can "less" through the error log (<code>less error.log</code>), look at the last few entires (<code>tail error.log</code>) or run the command <code>tail -f error.log</code> which will display new error messages as they are appended to the file. Use <br />
<code>^C</code> to break out of <code>tail -f</code> .<br />
<br />
== Checking MySQL ==<br />
<br />
First check that MySQL is running by <br />
<br />
$ mysql -u root<br />
<br />
You should see<br />
<br />
Welcome to the MySQL monitor. Commands end with ; or \g.<br />
Your MySQL connection id is 1<br />
Server version: 5.0.51a-3ubuntu5 (Ubuntu)<br />
<br />
Type 'help;' or '\h' for help. Type '\c' to clear the buffer.<br />
<br />
mysql> <br />
<br />
Enter <code>exit</code> to exit<br />
<br />
mysql> exit<br />
Bye<br />
$<br />
<br />
== Reboot and Test ==<br />
<br />
Now reboot the system (<code>System</code>, <code>Quit</code>, <code>Restart</code>).<br />
<br />
Now connect to<br />
"http://localhost/" using a browser on your machine and/or to your<br />
server from a browser on a remote machine. You should see the page '''It Works''' indicating that Apache is running.<br />
<br />
This is also a good time to check that 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 <code>Keyboard Interactive</code> to the list of "Authentication methods" under "Authentication" if it's not already there. <br />
<br />
Finally test that MySQL is running.<br />
<br />
$ mysql -u root<br />
...<br />
mysql> <br />
mysql> exit<br />
Bye<br />
$<br />
<br />
Currently the MySQL password is empty so we didn't need a password.<br />
We will take care of that now.<br />
<br />
== MySQL Security Issuses ==<br />
As initially set up, MySQL is a very open system. There are anonymous accounts with full privileges for some databases and the root accounts are not password protected. See e.g. http://dev.mysql.com/doc/refman/5.0/en/default-privileges.html for information on this. We recommend removing the anonymous accounts and giving passwords to the root accounts. There are three root accounts, one is <code>root@localhost</code>, one is <code>root@127.0.0.1</code> and the third is <code>root@host_name</code> where <code>host_name</code> is the name of your server. To find this name, do the following <br />
<br />
$ mysql -u root<br />
mysql> SELECT Host, User, Password FROM mysql.user;<br />
<br />
You will see a table with six entries. For <code>localhost</code> you will see three Users, <code>root</code> and <code>debian-sys-maint</code> and one with an empty name (the anonymous user). The other listed Host (with a <code>root</code> user and also one with an empty name) is the name of your server which we will denote by <code>host_name</code>. <br />
<br />
First we will remove the anonymous accounts. <br />
<br />
mysql> DELETE FROM mysql.user WHERE User = <nowiki>''</nowiki>;<br />
mysql> FLUSH PRIVILEGES;<br />
<br />
Now using the up arrow key repeat the command<br />
<br />
mysql> SELECT Host, User, Password FROM mysql.user;<br />
<br />
and you should get a table with only four users (three <code>root</code> and one <code>debian-sys-maint</code>). <br />
<br />
Now we will assign a password to these <code>root</code> accounts. <br />
<br />
In the third command below, replace <code>host_name</code> with the name of the server host. In all commands replace <code>newpwd</code> with your choosen MySQL <code>root</code> password. As was said above, '''Do not forget what you enter here'''. Also remember that this is the password for the MySQL <code>root</code> user, not the Ubuntu linux system <code>root</code> user. Below we refer to this as <code>&lt;mysql root password&gt;</code><br />
<br />
mysql> UPDATE mysql.user SET password=PASSWORD('newpwd') WHERE host='localhost' and user='root';<br />
mysql> UPDATE mysql.user SET password=PASSWORD('newpwd') WHERE host='127.0.0.1' and user='root';<br />
mysql> UPDATE mysql.user SET password=PASSWORD('newpwd') WHERE host='host_name' and user='root';<br />
mysql> FLUSH PRIVILEGES;<br />
<br />
Now use your up arrow key to run the command<br />
<br />
mysql> SELECT Host, User, Password FROM mysql.user;<br />
<br />
and you should see that all three users now have passwords (which will be displayed in encrypted form).<br />
<br />
Then exit MySQL<br />
<br />
mysql> exit<br />
Bye<br />
$<br />
<br />
<br />
and test that all is well:<br />
<br />
$ sudo /etc/init.d/mysql restart<br />
password:<your password><br />
$ mysql -u root -p <br />
Enter Password: <mysql root password><br />
<br />
You should see<br />
<br />
Welcome to the MySQL monitor ...<br />
mysql><br />
<br />
Enter<br />
<br />
mysql> SELECT Host, User, Password FROM mysql.user;<br />
<br />
and you should see encrypted passwords for all three accounts. Note that the way MySQL is set up, you can only gain access to the <code>localhost</code> account, not to the <code>host_name</code> account but setting a password for the <code>host_name</code> account is a safer thing to do in case the set up gets changed. Now exit MySQL<br />
<br />
mysql> exit<br />
Bye<br />
$ <br />
<br />
and congratulate yourself. You are now ready for the next and hopefully easy part, installing WeBWorK.<br />
<br />
== Downloading the WeBWorK System Software and Problem Libraries ==<br />
We are finally at the point where we can start downloading and installing WeBWorK. We will use CVS to download WeBWorK. This is easy and it will also make it easy to update the system in the future. Note that the following are rather long commands; it is much easier to copy (<code>^C</code>) them from this document and paste (<code>&lt;Shift&gt; &lt;Ctrl&gt; &lt;V&gt;</code>) them in a terminal window<br />
<br />
$ cd<br />
$ cd downloads<br />
<br />
$ cvs -d :pserver:anoncvs@cvs.webwork.rochester.edu:/webwork/cvs/system checkout -r rel-2-4-dev webwork2 pg<br />
$ cvs -d :pserver:anoncvs@cvs.webwork.rochester.edu:/webwork/cvs/asu checkout database_problems<br />
<br />
The first download gives you the latest released version with patches (don't be misled by the <code>dev</code> extension --- this is not a development version).<br />
The second download contains the WeBWorK National Problem Library. This now includes the Rochester and Union Libraries along with others as sunlibraries. There is quite a bit of overlap between these libraries but now you system is loaded with many thousands of WeBWorK problems (over 13,000 in the National Problem Library main collection alone).<br />
<br />
== Installing WeBWorK ==<br />
=== Move the System into the Required Directories ===<br />
As <code>root</code> create a <code>webwork</code> directory under <code>/opt</code> and move directories there. <br />
<br />
$ su<br />
<root password><br />
# mkdir /opt/webwork<br />
# mv webwork2 /opt/webwork/<br />
# mv pg /opt/webwork/<br />
<br />
Now create the <code>courses</code> and <code>libraries</code> directories under <code>webwork</code> and copy and move content there.<br />
<br />
# mkdir /opt/webwork/courses<br />
# mkdir /opt/webwork/libraries<br />
# mv database_problems/ /opt/webwork/libraries/<br />
# cd /opt/webwork/webwork2/courses.dist<br />
# cp *.lst /opt/webwork/courses/<br />
# cp -r modelCourse/ /opt/webwork/courses/<br />
<br />
=== Setting Permissions ===<br />
<br />
The PG installation directory and files should be owned by root and not writable by other users:<br />
<br />
# cd /opt/webwork/pg<br />
# chown -R root:root .<br />
# chmod -R u+rwX,go+rX .<br />
<br />
Most WeBWorK directories and files should also be owned by root and not writable by other users:<br />
<br />
# cd /opt/webwork/webwork2<br />
# chown -R root:root .<br />
# chmod -R u+rwX,go+rX .<br />
<br />
Certain data directories need to be writable by the web server. These are <code>DATA</code>, <code>courses</code>, <code>htdocs/tmp</code>, <code>logs</code>, and <code>tmp</code>. It is convenient to give WeBWorK administrators access to these directories as well, so they can perform administrative tasks such as removing temporary files, creating and editing courses from the command line, managing logs, and so on. We will create a new group called <code>wwdata</code>, containing both the WeBWorK administrators and the web server.<br />
<br />
# Select <code>System</code>, <code>Administration</code> and then <code>Users and Groups</code><br />
# Click on <code>Unlock</code><br />
# Enter <code>&lt;your password&gt;</code> and click <code>Authenticate</code><br />
# Select <code>Manage Groups</code><br />
# Click <code>Add Group</code> <br />
# For <code>Group name</code> enter <code>wwdata</code><br />
# Under <code>Group Members</code> select yourself and click <code>OK</code><br />
# Click <code>Close</code><br />
<br />
If there are other users who will also be administering WeBWorK files,<br />
now is a good time to add them. And remember to add them to the <code>wwdata</code> group as above.<br />
<br />
Because system users are not shown by default, we can not simply use the <code>Group Manager</code> to add the Apache2 webserver (which runs as <code>www-data</code>) to the <code>wwdata</code><br />
group so we will do this by hand.<br />
<br />
# cd /etc<br />
# cp group group.bak1<br />
# gedit group<br />
<br />
<br />
# In the gedit window scroll to the last line. <br />
# It should look like <code>wwdata:x:1001:<your userid></code><br />
# Append to this line <code>,www-data</code><br />
# Then Save and Quit<br />
<br />
<br />
<br />
You can check that this succeeded in a terminal window by entering<br />
<br />
# exit<br />
$ id <your userid><br />
<br />
and then you should see <code>wwdata</code> listed under groups. Also<br />
<br />
$ id www-data<br />
<br />
should show wwdata listed under groups. Now we make the WeBWorK directories that need to be writable by the web server have <code>wwdata</code> as their group. The following are rather long commands; you might want to copy them and paste them into your terminal window rather than typing them.<br />
<br />
$ su<br />
<root password><br />
# cd /opt/webwork/webwork2/<br />
# chgrp -R wwdata DATA ../courses htdocs/tmp logs tmp<br />
# chmod -R g+w DATA ../courses htdocs/tmp logs tmp<br />
# find DATA/ ../courses/ htdocs/tmp logs/ tmp/ -type d -a ! -name CVS -exec chmod g+s {} \;<br />
# exit<br />
$<br />
<br />
== Configuring the Shell ==<br />
<br />
To make working with WeBWorK easier, there are a couple of changes you can make to your shell environment.<br />
<br />
Add the WeBWorK <code>bin</code> directory to your path. This will allow you to run WeBWorK command-line utilities without typing the full path to the utility. Goto your home directory and backup your <code>.bashrc</code> file<br />
<br />
$ cd<br />
$ cp .bashrc .bashrc.bak1<br />
<br />
Now edit <code>.bashrc</code><br />
<br />
$ gedit .bashrc<br />
<br />
After the last line add the two lines:<br />
<br />
export PATH=$PATH:/opt/webwork/webwork2/bin<br />
export WEBWORK_ROOT=/opt/webwork/webwork2<br />
<br />
Then save the file and Quit.<br />
<br />
Close your Terminal Window and open a new one so the above changes<br />
take effect. You can check that they have by<br />
<br />
$ echo $PATH<br />
$ echo $WEBWORK_ROOT<br />
<br />
== Checking Module Dependancies ==<br />
<br />
<br />
<br />
WeBWorK includes a script called <code>check_modules.pl</code> that verifies that the needed programs and Perl modules are installed on your system. Run this script to make sure you have installed the required programs and Perl modules.<br />
<br />
$ check_modules.pl apache2<br />
<br />
Scroll up and look through the listing. It should find everything except <code>PHP::Serialization</code>, <code>SOAP::Lite</code>, <code>MIME::Parser</code> and <code>XMLRPC::Lite</code> which are only required if you plan to use WeBWorK with Moodle and <code>tth</code> which is a deprecated display mode. If something is missing (flagged by <code>**</code>), look back through these instructions and/or look at 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.<br />
<br />
== Configuring WeBWorK ==<br />
<br />
=== Making Copies of the Distribution Configuration Files ===<br />
<br />
Before configuring the system, you must make local copies of the <code>global.conf</code> and <code>database.conf</code> configuration files, located in <code>/opt/webwork/webwork2/conf/</code> . Since these are owned by <code>root</code><br />
<br />
$ su<br />
<root password><br />
# cd /opt/webwork/webwork2/conf<br />
# cp global.conf.dist global.conf<br />
# cp database.conf.dist database.conf<br />
<br />
=== Global Configuration ===<br />
<br />
Most WeBWorK configuration is done in the file <code>/opt/webwork2/conf/global.conf</code>. This file provides system-wide configuration settings, and defaults for course settings. Any setting in this file can be overridden in the <code>course.conf</code> file for a particular course. To override a setting for a course, just put the new setting (using the same syntax as is in <code>global.conf</code>) in the <code>course.conf</code> file.<br />
<br />
There are several options that must be set for WeBWorK to work with your system. The rest of the file consists of customization options. Now edit <code>global.conf</code><br />
<br />
# cd /opt/webwork/webwork2/conf<br />
# gedit global.conf<br />
<br />
WeBWorK uses the DateTime module. DateTime is supposed to be able to determine the local timezone itself without you having to enter it but this often fails so it is best to just set it here. For is a list of timezones recognized by DateTime go to<br />
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 <code>DateTime::TimeZone::America::New_York</code> and you should replace <code>$siteDefaults{timezone} = "";</code> by <code>$siteDefaults{timezone} = "America/New_York";</code> <br />
<br />
# Search for <code>$siteDefaults{timezone} = "";</code> and enter your local timezone.<br />
<br />
At this point <code>TtH</code> is a deprecated display mode which we didn't install so we have to remove it from the listof possible display modes. <br />
<br />
# Search for <code>formattedText</code> and comment out the line <code>"formattedText", # format math expressions using TtH</code><br />
so it becomes<br />
<br />
# "formattedText", # format math expressions using TtH<br />
<br />
We need to set a password that WeBWorK uses when it communicates with the MySQL database. Note that this is not the same as the <code>&lt;mysql root password&gt;</code> which is the password the MySQL root user uses.<br />
# Search for <code>$database_password = "";</code> and replace this by <br /> <code>$database_password = "database_password";</code> <br />
where of course you should replace 'database_password' with your own password. Remember this password as we will need it below.<br />
<br />
WeBWorK sends mail in three instances. The PG system sends mail to report answers to questionnaires and free-response problems. The mail merge module is used to send mail to course participants, i.e. to report scores. The feedback module allows participants to send mail to course instructors.<br />
<br />
To send mail, WeBWorK needs the address of an SMTP server. Normally you will use the address of your school's SMTP server. If the local machine is running an SMTP server, use <code>localhost</code>. IMPORTANT: Our instructions above did not install an SMTP server so you will have to install and configue one if you do not use your school's SMTP server. When connecting to the SMTP server, WeBWorK must also send an email address representing the sender of the email (this has nothing to do with the <code>From</code> address on the mail message). Edit the lines<br />
$mail{smtpServer} = 'mail.yourschool.edu'; <br />
$mail{smtpSender} = 'webwork@yourserver.yourschool.edu';<br />
<br />
entering the appropriate information.<br />
<br />
If you want WeBWorK questionnaires or similar things from different courses to be mailed to a central person or persons (e.g. the WeBWorK administrator), edit the lines<br />
<br />
$mail{allowedRecipients} = [<br />
#'prof1@yourserver.yourdomain.edu',<br />
#'prof2@yourserver.yourdomain.edu',<br />
];<br />
<br />
appropriately removing the <code>#</code> and using the professor(s) actual email address(es). In order to have professors from individual courses receive such email, this <br />
should be set in course.conf to the addresses of professors of each course.<br />
<br />
Then save the file and Quit.<br />
<br />
<br />
Now become a regular user again<br />
<br />
# exit<br />
$<br />
<br />
WeBWorK uses a single database, called <code>webwork</code>, for all courses. We will create the <code>webwork</code> database now.<br />
<br />
To do this do the following (before you just copy, paste and hit <code>&lt;Enter&gt;</code> notice that you have to replace <code>database_password</code> with the password you set when editing <code>global.conf</code> above):<br />
<br />
$ mysql -u root -p mysql<br />
Enter password: <mysql root password><br />
mysql> CREATE DATABASE webwork;<br />
mysql> GRANT SELECT, INSERT, UPDATE, DELETE, CREATE, ALTER, DROP, LOCK TABLES ON webwork.* TO webworkWrite@localhost IDENTIFIED BY 'database_password';<br />
mysql> exit<br />
Bye<br />
$ <br />
<br />
where as we said replace <code>database_password</code> with the password you set when editing <code>global.conf</code> above.<br />
<br />
Since version 2.3.0 WeBWorK has an automatic database upgrade system. Rather than manually issuing SQL commands to make changes to the database, or using ad-hoc scripts like wwdb_addgw, there is a single script called <code>wwdb_upgrade</code> that applies any necessary updates. It should be run when creating a new database, and any time you upgrade WeBWorK.<br />
<br />
$ /opt/webwork/webwork2/bin/wwdb_upgrade -v<br />
<br />
=== jsMath Settings ===<br />
<br />
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 <code>webwork2/htdocs/jsMath/jsMath-fonts.tar.gz</code>, and you need to unpack this tarball before jsMath will work properly. Use the command<br />
<br />
$ su<br />
<root password><br />
# cd /opt/webwork/webwork2/htdocs/jsMath<br />
# tar vfxz jsMath-fonts.tar.gz<br />
<br />
This will unpack the archive. Since there are 20,000 tiny files, it can take a little while, so the <code>v</code> 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.<br />
<br />
<br />
== Configuring Apache ==<br />
WeBWorK ships with an Apache config file that needs to linked into your Apache configuration process. The file is named <code>webwork.apache2-config.dist</code> and located in the <code>conf</code> directory. First, copy the file to <code>webwork.apache2-config</code>:<br />
<br />
# cd /opt/webwork/webwork2/conf<br />
# cp webwork.apache2-config.dist webwork.apache2-config<br />
<br />
and now link it into your Apache configuration process<br />
<br />
# cd /etc/apache2/conf.d<br />
# ln -s /opt/webwork/webwork2/conf/webwork.apache2-config webwork.conf<br />
<br />
Then restart Apache <br />
<br />
# apache2ctl graceful<br />
# exit<br />
$<br />
<br />
== Test your configuration ==<br />
<br />
# Test the <code>/webwork2</code> location by visiting <code>http://yourserver.yourschool.edu/webwork2</code>. You should see the WeBWorK home page with no courses listed. Actually the directory <code>/opt/webwork/courses/</code> does contain the <code>modelCourse</code> but the <code>modelCourse</code> is not a real course so you will get an error message if you try to log into it. It will be used a as model for setting up other courses. For this reason <code>/opt/webwork/courses/modelCourse/</code> contains a file named <code>hide_directory</code> and so the <code>modelCourse</code> is not visible.<br />
# Test the <code>/webwork2_files</code> location by visiting <code>http://yourserver.yourschool.edu/webwork2_files</code>. You should see the "WeBWorK Placeholder Page".<br />
# You cannot test the <code>/webwork2_course_files</code> location until you have created a course.<br />
<br />
==If Something is Wrong ==<br />
If something is wrong one of the first things to check is that the config files have been edited correctly (e.g. one time a wrapped line in <code>global.conf</code> caused me problems, another time it was a missing single quote). A quick way to check this is to do a <code>diff</code> between the edited and distributed versions and check that <code>diff</code> reports the changes you made and only those.<br />
<br />
# exit<br />
$<br />
$ cd /etc/apache2/<br />
$ diff apache2.conf apache2.conf.bak1<br />
$ cd /opt/webwork/webwork2/conf/<br />
$ diff global.conf global.conf.dist<br />
$ diff database.conf database.conf.dist<br />
$ diff webwork.apache2-config webwork.apache2-config.dist <br />
<br />
If something is wrong and you fix it, you will have to restart Apache for the changes to take effect<br />
<br />
$ su<br />
<root password><br />
# apache2ctl graceful<br />
# exit<br />
$<br />
<br />
== Create the admin Course ==<br />
<br />
[[Course Administration]] gives information about creating courses. Here we will give explicit instructions for doing this.<br />
<br />
$ su<br />
<root password><br />
# newgrp wwdata<br />
# umask 2<br />
# cd /opt/webwork/courses<br />
# /opt/webwork/webwork2/bin/addcourse admin --db-layout=sql_single --users=adminClasslist.lst --professors=admin<br />
# exit<br />
# exit<br />
$<br />
<br />
Now goto <code>http://yourserver.yourschool.edu/webwork2</code> and should see the WeBWorK home page with <code>Course Adninistration</code> listed at the top. Click on it and login with Username <code>admin</code> and Password <code>admin</code> . This first thing you should do is to click on <code>Password/Email</code> and change <code>admin</code> 's password to something more secure than <code>admin</code> . <br />
<br />
Unless you choose oherwise, users with <code>professor</code> privilges in the <code>admin</code> course (i.e. WeBWorK administrators) will automatically be added to new courses with <code>professor</code> privilges and the same password as in the <code>admin</code> course. Initially the only such user is <code>admin</code> (hopefully you are not confused by the fact that the course <code>admin</code> has a user named <code>admin</code>). It's usually convenient make yourself a WeBWorK administrator. To do this (assuming you are logged in as <code>admin</code> to the <code>admin</code> course at <code>http://yourserver.yourschool.edu/webwork2/admin</code> )<br />
# Click on <code>Classlist Editor</code> in the left panel<br />
# Check <code>Add 1 student(s)</code> and click <code>Take Action!</code><br />
# Enter the appropiate information (you can leave the last three items blank) and click <code>Add Students</code><br />
# Click on <code>Classlist Editor</code> in the left panel again<br />
<br />
# When you enter a new student, by default their <code>Student ID</code> is used as their password. We'll change this now.<br />
# Select yourself with a check mark and then check <code>Give new password to Selected users</code> or just check <code>Give new password to All users</code> (as a safely mechanism you can not change the password for the user you are logged in as, currently <code>admin</code>, this way) and then click <code>Take Action!</code><br />
# Enter the password, check <code>Save changes</code> and then click <code>Take Action!</code><br />
# Finally give yourself <code>professor</code> privilges by selecting yourself with a check mark, checking <code>Edit Selected users</code> and then clicking <code>Take Action!</code> (or by just clicking on the "pencil" next to your login name which is a much faster way to edit classlist data for a single user)<br />
# Now at the far right change <code>Permission Level</code> from <code>student</code> to <code>professor</code><br />
# Check <code>Save changes</code> and then click <code>Take Action!</code><br />
<br />
At some point you will probably want to hide the <code>admin</code> course so that it is not listed on the WeBWorK home page. As we noted above the <code>modelCourse</code>, which is already hidden, is not a real course so you will get an error message if you try to log into it. This is a good reason to hide it. The <code>modelCourse</code> is very useful as a model (hence its name) for setting up other courses. The <code>admin</code> course is used for administering WeBWorK and even though regular users can not log into it (you did change the <code>admin</code> password, didn't you!!), it a little bit cleaner and safer to hide it from prying eyes. <br />
To hide a course place a file named <code>hide_directory</code> in the course directory and it will not show up in the courses list on the WeBWorK home page. It will still appear in the Course Administration listing. If you do this you will still be able to access the <code>admin</code> course using the URL <code>http://yourserver.yourschool.edu/webwork2/admin</code> but you will not see a link for it on the WeBWorK home page <code>http://yourserver.yourschool.edu/webwork2</code> . Let's hide the <code>admin</code> course.<br />
<br />
$ sudo cp /opt/webwork/courses/modelCourse/hide_directory /opt/webwork/courses/admin<br />
password:<your password><br />
<br />
<br />
Now goto <code>http://yourserver.yourschool.edu/webwork2</code> and no course will be listed.<br />
<br />
== Starting and Stoping Apache, MySQL and the GNOME desktop GUI ==<br />
If you make changes to the system, you will have to restart <code>apache2</code> before the changes take effect. On rare ocassions you may need to restart <code>MySQL</code>. <br />
=== Starting and Stoping Apache ===<br />
You have to run these commands as <code>root</code>.<br />
<br />
To start or restart (i.e. stop and then start) the <code>apache2</code> webserver run the command <br />
<br />
$ sudo apache2ctl graceful<br />
password:<your password><br />
<br />
To stop the Apache webserver run the command <br />
<br />
$ sudo apache2ctl stop<br />
password:<your password><br />
<br />
You can also start or stop apache2, listed as <code>Web server (apache2)</code>, by using the GUI interface.<br />
# Select <code>System</code>, <code>Administration</code> and then <code>Services</code><br />
# Scroll down to <code>Web server (apache2)</code><br />
# If <code>apache2</code> is running, uncheck its check box and click <code>Close</code> to stop it<br />
# If <code>apache2</code> is stopped, check its check box and click <code>Close</code> to start it<br />
<br />
Another method is to use the <code>init.d</code> script <code>apache2</code>. Run<br />
$ sudo /etc/init.d/apache2<br />
password:<your password><br />
and you will get a list of allowed commands (<code>start</code>, <code>stop</code>, <code>restart</code>, etc).<br />
<br />
Note that in an earlier version of Ubuntu I found using the GUI interface somewhat unreliable.<br />
<br />
=== Starting and Stoping MySQL ===<br />
You have to run these commands as <code>root</code>.<br />
<br />
To start the <code>MySQL</code> server run the command <br />
<br />
$ sudo /etc/init.d/mysql start<br />
password:<your password><br />
<br />
To stop the <code>MySQL</code> server run the command <br />
<br />
$ sudo /etc/init.d/mysql stop<br />
password: <your password><br />
<br />
To restart the <code>MySQL</code> server run the command <br />
<br />
$ sudo /etc/init.d/mysql restart<br />
password: <your password><br />
<br />
You can also start or stop MySQL, listed as <code>Database server (mysql)</code>, by using the GUI interface.<br />
<br />
# Select <code>Desktop</code>, <code>Administration</code> and then <code>Services</code><br />
# Scroll down to <code>Database server (mysql)</code><br />
# If <code>mysql</code> is running, uncheck its check box and click <code>Close</code> to stop it<br />
# If <code>mysql</code> is stopped, check its check box and click <code>Close</code> to start it<br />
<br />
=== Starting and stopping the GNOME desktop GUI ===<br />
<br />
The GNOME desktop is automatically started when the system boots. <br />
<br />
To stop <code>GNOME</code> so that you only have a standard terminal window run the following in a standard terminal window<br />
<br />
$ sudo /etc/init.d/gdm stop <br />
password: <your password><br />
<br />
If you stopped <code>GNOME</code> and want to restart it run the following in a standard terminal window<br />
<br />
$ sudo /etc/init.d/gdm start <br />
password: <your password><br />
<br />
==Install the WeBWorK Problem Libraries ==<br />
Before we create a real course we will install the WeBWorK Problem Libraries.<br />
<br />
===Install the National Problem Library ===<br />
The <code>National Problem Library</code> consists of both WeBWorK problems and methods for searching and selecting problems. Also it contains as sub libraries many of the other standard libraries. Normally this library is referred to as the <code>ProblemLibrary</code> but the downloaded CVS directory for it is named <code>database_problems</code>. So the first thing we do is to link <code>ProblemLibrary</code> to <code>database_problems</code>. <br />
<br />
$ cd /opt/webwork/libraries/<br />
$ sudo ln -s database_problems ProblemLibrary<br />
password: <your password><br />
<br />
Next we have to edit <code>global.conf</code>.<br />
<br />
$ cd /opt/webwork/webwork2/conf<br />
$ su<br />
Password: <root password><br />
# gedit global.conf<br />
<br />
# Search for <code>problemLibrary</code> and replace <code>$problemLibrary{root} = "";</code> by <br /> <code>$problemLibrary{root} = "/opt/webwork/libraries/ProblemLibrary";</code> <br />
<br />
Then save the file and quit. And return to a regular user<br />
<br />
#exit<br />
$<br />
<br />
We now create a database, called <code>ProblemLibrary</code>, for for the Problem Library.<br />
To do this do the following:<br />
<br />
$ mysql -u root -p mysql<br />
Enter password: &lt;mysql root password&gt;<br />
mysql> CREATE DATABASE ProblemLibrary;<br />
mysql> GRANT SELECT ON ProblemLibrary.* TO webworkWrite@localhost;<br />
mysql> exit<br />
Bye<br />
$ <br />
<br />
Update mysql<br />
<br />
$ NPL-update<br />
<br />
This has to convert a lot of data so please be patient; it can take a long time.<br />
<br />
If at some time in the future you want to upgrade the Problem Library, the process<br />
is simpler. Optionally remove the previous copy of the<br />
library, unpack the new copy in the same place, and run NPL-update.<br />
<br />
===Set up the Rochester and Union Libraries ===<br />
<br />
First we need to edit <code>global.conf</code> one last time<br />
<br />
$ cd /opt/webwork/webwork2/conf<br />
$ su<br />
Password: <root password><br />
# gedit global.conf<br />
<br />
# Search for <code>courseFiles{problibs}</code> and scroll down several lines to the line <br /> <code># rochesterLibrary =&gt; "Rochester",</code><br />
# Uncomment this line (i.e. remove the <code>#</code>) so it becomes <br /> <br />
&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp; <code>rochesterLibrary =&gt; "Rochester",</code><br />
# Directly below this line add the line <br /> <br />
&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp; <code>unionLibrary =&gt; "Union",</code><br />
# Search for <code>macrosPath</code> and scroll down several lines to the line <br /> <code>$pg{directories}{macros},</code><br />
# After this line add the line: <br /> <code>'/opt/webwork/libraries/database_problems/macros/Union',</code> <br />
<br />
Don't forget the coma (<code>,</code>) at the end of these lines. Then save the file and quit.<br />
<br />
Since we have edited <code>global.conf</code> a lot and this is a very critical file, it would be a good idea to run<br />
<br />
<br />
# exit<br />
$ diff global.conf global.conf.dist<br />
<br />
and check that you haven't made any mistakes (e.g. by introducing an inadvertant line break, etc).<br />
<br />
We next put links to the Rochester and Union Libraries in the <code>modelCourse</code> so that when we create courses copying templates from the <code>modelCourse</code>, these libraries will be available. Skip this step if you usually only want to use National Problem Library.<br />
<br />
$ cd /opt/webwork/courses/modelCourse/templates/<br />
$ sudo ln -s /opt/webwork/libraries/database_problems/Union unionLibrary<br />
password: <your password><br />
$ sudo ln -s /opt/webwork/libraries/database_problems/Rochester rochesterLibrary<br />
<br />
If you want to put another library into the <code>modelCourse</code>, just do the analogous thing. If you just want the additional library in a particular course, add the link in the <code>templates</code> directory of that course. If you look in the directory <code>/opt/webwork/libraries/database_problems/</code> you might find other libraries that are not yet listed in <code>global.conf</code> (like <code>Union</code> above) and these can be added in the same way we added <code>Union</code>. Usually they do not require additional macros like <code>Union</code> did. Finally if you add a library with non standard symbols in the name (e.g. <code>uva-statLibrary</code>) you have to use single quotes when adding it to <code>global.conf</code>, e.g. <br><br />
&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp; <code>'uva-statLibrary' => "UVA-Stat",</code> <br><br />
It's easier to just avoid such names.<br />
<br />
==Create Your First Actual Course ==<br />
<br />
Now log into the <code>admin</code> course ( <code>http://yourserver.yourschool.edu/webwork2/admin</code> ) as yourself or <code>admin</code> and <br />
# click on <code>Add Course</code><br />
# For <code>Course ID</code> enter <code>myTestCourse</code><br />
# For <code>Course Title</code> enter <code>My Test Course</code><br />
# Enter your institution<br />
# Leave <code>Add WeBWorK administrators to new course</code> checked<br />
# Add an additional instructor if you wish<br />
# Copy templates from: <code>modelCourse</code> (the default action)<br />
# Select sql_single for the database layout.<br />
# Click on <code>Add Course</code><br />
# Click <code>Log into myTestCourse</code><br />
<br />
and log in either as <code>admin</code> or yourself.<br />
<br />
At some point you will probably want to "hide" <code>myTestCourse</code> from general view but you already know how to do that.<br />
<br />
==Test that Things are Working Properly ==<br />
<br />
We will test out a few important parts of WeBWorK. If you run into problems, you should look at the Apache error log which is located at <code>/var/log/apache2/error.log</code>.<br />
<br />
Click on <code>Hmwk Sets Editor</code> on the <code>Main Menu</code>. Then select (by clicking the circle button) <code>Import</code>, select <code>setDemo.def</code> from the <code>from</code> drop down list and select <code>all current users</code> from the <code>assigning this set to</code> drop down list. Then hit <code>Take Action!</code><br />
<br />
Now click on <code>Homework Sets</code> on the <code>Main Menu</code> and click on <code>Demo</code>. Then look at the problems. Mathematical equations should be typeset. If not, edit the file <code>Constants.pm</code> in the directory <code>/opt/webwork/webwork2/lib/WeBWorK</code>. Change the line <code>$WeBWorK::PG::ImageGenerator::PreserveTempFiles = 0;</code> to <code>...::PreserveTempFiles = 1;</code>. Then restart Apache and view the first couple problems or some new ones. Then look in the directory <code>/opt/webwork/webwork2/tmp/</code>. <code>cd</code> to one of the <code>ImageGenerator.../tmp/</code> directories and look at the error and log files there. When you fix the problem remember to edit <code>...::PreserveTempFiles = 1;</code> back to 0 and restart Apache or you will be saving a lot of unnecessary files. Another useful trick is to try downloading a hard copy of an assignment and then (assuming there are errors) looking at the various log files that are linked to on the output page.<br />
<br />
When you continue looking at problems you will get an error when you try to look at Problem 6 because we have not 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 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). <br />
<br />
Next click on <code>Prob. List</code> to bring back the Problem List Page and click on <code>Download a hardcopy of this homework set</code>. The page is a little complicated because you are a professor but you can just scroll to the bottom and click on <code>Generate hardcopy for selected users and selected sets</code>. You will get an error (because of the bad Problem 6) but just click <code>Download Hardcopy</code> to get what was generated. Also you can see links to various <br />
informational files that are available if you run into problems (normally these files are removed if there are no errors).<br />
<br />
Another thing to do is to use <code>Email</code> on the <code>Main Menu</code>. Again this page is a little complicated because you can do a lot of things with it (including mail merge) but at this point just select yourself in the list to the right and hit <code>Send Email</code> at the bottom. You should receive two emails. One is the message you just sent and the other is an email with subject "WeBWorK email sent" giving information on your mailing. <br />
<br />
As a final test click on <code>Library Browser</code> on the <code>Main Menu</code>. Click <code>Problem Library </code><br />
and select a <code>Subject</code>, <code>Chapter</code> and <code>Section</code> and then hit <code>View Problems</code>. The first 20 of your selected problems will be displayed. You can also test that you can access any additional Problem Libraries that you installed.<br />
<br />
If all the above tests work, you can be pretty confident that WeBWorK is working properly.<br />
<br />
Go back to <code>Hmwk Sets Editor</code> on the <code>Main Menu</code>. Then select (by clicking the circle button) <code>Import</code>, select <code>setOrientation.def</code> from the <code>from</code> drop down list and select <code>all current users</code> from the <code>assigning this set to</code> drop down list. Then hit <code>Take Action!</code>. Then go through the Orientation problems. This is a good first set to use for introducing students to WeBWorK.<br />
<br />
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.<br />
Click on <code>Classlist Editor</code> on the <code>Main Menu</code>.<br />
Then select (by clicking the circle button) <code>Add 1 student(s)</code>and hit <code>Take Action!</code>. Add one student, say Jane Smith, with <code>Student ID</code> <code>1234</code> and <code>Login Name</code> <code>jsmith</code>.<br />
Jane Smith's initial password will be her <code>Student ID</code> <code>1234</code>. Now login as Jane Smith and play around a little.<br />
<br />
==Optional Configurations==<br />
'''Optional A''' stores WeBWorK's "temporary" files in a separate partition. <br />
'''Optional B''' installs and configures a lightweight webserver to serve static files.<br />
'''Optional C''' configures Apache so that access to WeBWorK will be through SSL.<br />
<br />
===Implement Optional A (wwtmp)===<br />
<br />
Now is the time to implement '''Optional A''' if you choose to do so. Actually you can do this at any time and your active courses will continue to function seemingly without change. The only change behind the scenes will be that temporary files will be stored in a different location.<br />
<br />
First we set the group and permissions for the <code>wwtmp</code> directory<br />
<br />
$ su<br />
<root password><br />
# cd /var/www<br />
# chgrp wwdata wwtmp<br />
# chmod ug+w wwtmp<br />
# chmod g+s wwtmp<br />
<br />
Next we have to edit <code>global.conf</code> so that WeBWorK uses the new <code>wwtmp</code> directory. Since we have a working WeBWorK system, first we make a backup copy of <code>global.conf</code>.<br />
<br />
<br />
# cd /opt/webwork/webwork2/conf<br />
# cp global.conf global.bak1<br />
# gedit global.conf<br />
<br />
Now edit <code>global.conf</code>. Find the lines <br />
<br />
$webworkDirs{htdocs_temp} = "$webworkDirs{htdocs}/tmp";<br />
$webworkURLs{htdocs_temp} = "$webworkURLs{htdocs}/tmp";<br />
and replace them by <br />
#$webworkDirs{htdocs_temp} = "$webworkDirs{htdocs}/tmp";<br />
#$webworkURLs{htdocs_temp} = "$webworkURLs{htdocs}/tmp";<br />
$webworkDirs{htdocs_temp} = '/var/www/wwtmp';<br />
$webworkURLs{htdocs_temp} = '/wwtmp';<br />
<br />
Next find the lines <br />
<br />
$courseDirs{html_temp} = "$courseDirs{html}/tmp";<br />
$courseURLs{html_temp} = "$courseURLs{html}/tmp";<br />
and replace them by <br />
#$courseDirs{html_temp} = "$courseDirs{html}/tmp";<br />
#$courseURLs{html_temp} = "$courseURLs{html}/tmp";<br />
$courseDirs{html_temp} = "/var/www/wwtmp/$courseName";<br />
$courseURLs{html_temp} = "/wwtmp/$courseName";<br />
<br />
Then save the file and quit. If you look at the <code>wwtmp</code> directory you will find it empty but after you restart apache and then access some WeBWorK problems, you will find temporary directories and files in <code>wwtmp</code>. Remember your have to restart apache for these changes to take effect.<br />
<br />
===Implement Optional B (lighttp)===<br />
<br />
As is the case for '''Optional A''' you can implement '''Optional B''' at any time and your active courses will continue to function seemingly without change. The only change behind the scenes will be that static images and pages will be served by a light weight web server.<br />
<br />
First we install the light weight webserver <code>lighttp</code><br />
<br />
# Open the <code>Synaptic Package Manager</code> (select <code>System</code>, <code>Administration</code>, <code>Synaptic Package Manager</code>). <br />
# Select <code>Search</code> <br />
# Search for <code>lighttp</code> and select it<br />
# In the pop up window <code>Mark additional required changes?</code> click <code>Mark</code> to accept the requirements.<br />
# Now click <code>Apply</code> and <code>Apply</code> again to confirm the changes.<br />
<br />
You can now quit the <code>Synaptic Package Manager</code>.<br />
<br />
Now we configure <code>lighttp</code>. First let's make a backup of the configuration file.<br />
<br />
<br />
$ su<br />
<root password><br />
# cd /etc/lighttpd<br />
# cp lighttpd.conf lighttpd.conf.bak1<br />
<br />
Now edit <code>lighttpd.conf</code>. <br />
<br />
# gedit lighttpd.conf<br />
<br />
Uncomment the line<br />
# "mod_status",<br />
so it becomes<br />
"mod_status",<br />
<br />
Search for the line<br />
server.document-root = "/var/www/"<br />
and under this line add the line<br />
alias.url = ("/webwork2_files/" => "/opt/webwork/webwork2/htdocs/")<br />
<br />
Apache2 is listening on port 80 so we set lighttp to listen on port 81. Find the line<br />
# server.port = 81<br />
and uncomment it <br />
server.port = 81<br />
<br />
Finally uncomment the line<br />
# status.status-url = "/server-status"<br />
so it becomes<br />
status.status-url = "/server-status"<br />
Then save the file and quit.<br />
<br />
Now restart lighttp<br />
<br />
$su<br />
<root password><br />
# /etc/init.d/lighttpd restart<br />
# exit<br />
$<br />
<br />
Note that you can just run <code>/etc/init.d/lighttpd</code> to get a list of all options.<br />
<br />
Now test your server by connecting to<br />
"http://localhost:81/" and/or connecting to your<br />
server from a browser on a remote machine. You should see the page '''It works!''' indicating that lighttp is running.<br />
<br />
You can check lighttp's status by connecting to<br />
"http://localhost:81/server-status" using a browser on your machine or from to "http://yourserver.yourschool.edu:81/server-status" from a browser on a remote machine.<br />
<br />
The Server-Status page doesn't indicate that lighttp is the web server, but it's certainly different than apache's Server-Status page "http://localhost/server-status".<br />
<br />
Next we configure WeBWorK to take advantage of lighttp.<br />
<br />
First let's make a backup copy of <code>global.conf</code> so that we can easily back out of these changes if necessary.<br />
<br />
# cd /opt/webwork/webwork2/conf<br />
# cp global.conf global.bak2<br />
<br />
<br />
Now edit <code>global.conf</code>. Note that while '''Optional B''' is independent of '''Optional A''', we assume most people implementing '''Optional B''' will have already implemented '''Optional A'''. Therefore we give instructions for editing <br />
global.conf assuming that '''Optional A''' has been implemented. If this is not the case, modify the instructions below accordingly. Also replace <code>yourserver.yourschool.edu</code> with the correct address.<br />
<br />
# gedit global.conf<br />
<br />
Find the line<br />
$webwork_htdocs_url = "/webwork2_files";<br />
and replace it by<br />
#$webwork_htdocs_url = "/webwork2_files";<br />
$webwork_htdocs_url = 'http://yourserver.yourschool.edu:81/webwork2_files';<br />
<br />
Find the line<br />
$webworkURLs{htdocs_temp} = '/wwtmp'<br />
and replace it by<br />
#$webworkURLs{htdocs_temp} = '/wwtmp';<br />
$webworkURLs{htdocs_temp} = 'http://yourserver.yourschool.edu:81/wwtmp';<br />
<br />
Find the line<br />
$courseURLs{html_temp} = "/wwtmp/$courseName";<br />
and replace it by<br />
#$courseURLs{html_temp} = "/wwtmp/$courseName";<br />
$courseURLs{html_temp} = "http://yourserver.yourschool.edu:81/wwtmp/$courseName";<br />
<br />
Then save the file and quit.<br />
<br />
Now restart apache and lighttp.<br />
<br />
$ sudo apache2ctl graceful<br />
password:<your password><br />
$ sudo /etc/init.d/lighttpd restart<br />
<br />
To test things go to your test course <code>http://yourserver.yourschool.edu/webwork2/myTestCourse/</code>. Before you login right click on the WeBWorK icon in the upper left hand corner of the login page. The click on Properties (or whatever is appropriate on your browser) and check that the image is being served from port 81 (something like <code>http://yourserver.yourschool.edu:81/webwork2_files/images/webwork_rectangle.png</code>. Then log into your course and view a problem with typeset equations (e.g. Problem 1 of the Demo set). Again right click on the typeset equation and check that the image is being served from port 81.<br />
<br />
===Implement Optional C (SSL)===<br />
'''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.<br />
<br />
I cribbed these directions from several sources, the main one being http://www.akadia.com/services/ssh_test_certificate.html.<br />
<br />
We will create and work in a <code>tmp</code> directory.<br />
<br />
$ cd<br />
$ mkdir tmp<br />
$ cd tmp<br />
<br />
First we create an RSA Private Key.<br />
<br />
$openssl genrsa -des3 -out server.key 1024<br />
<br />
When you are asked for a <code>pass phrase</code>, enter a phrase which we refer to as <code>&lt;my pass phrase&gt;</code> and then confirm it. Next generate a Certificate Signing Request<br />
openssl req -new -key server.key -out server.csr<br />
<br />
Enter the requested information. '''Important:''' when you are prompted for the <code>Common Name</code> enter your server's fully qualified domain name, something like <code>yourserver.yourschool.edu</code>. You can leave the last two items <br />
A challenge password []:<br />
An optional company name []:<br />
blank.<br />
<br />
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.<br />
<br />
$ cp server.key server.key.bak1<br />
$ openssl rsa -in server.key.bak1 -out server.key<br />
<br />
Next we generate a self-signed certificate which is good for 365 days<br />
<br />
$ openssl x509 -req -days 365 -in server.csr -signkey server.key -out server.crt<br />
<br />
Now we become root, move these files, and set their group and permission.<br />
<br />
$ su<br />
<root password><br />
# mv server.crt /etc/ssl/private<br />
# mv server.key /etc/ssl/private<br />
# cd /etc/ssl/private<br />
# chgrp ssl-cert server.*<br />
# chmod 640 server.*<br />
<br />
Next we enable the <code>mod_ssl</code> module<br />
# a2enmod ssl<br />
<br />
Now we have to configure Apache to use SSL.<br />
# cd /etc/apache2/sites-enabled/<br />
# cp default default.bak1<br />
# gedit default<br />
<br />
Replace the first line<br />
NameVirtualHost *<br />
by the two lines<br />
NameVirtualHost *:80<br />
NameVirtualHost *:443<br />
Now edit the next non blank line<br />
<VirtualHost *><br />
changing it to<br />
<VirtualHost *:80><br />
Next copy the entire section <br />
<VirtualHost *:80> <br />
...<br />
</VirtualHost><br />
(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.<br />
Edit the new second<br />
<VirtualHost *:80><br />
changing it to<br />
<VirtualHost *:443><br />
Now at the end of the file just above the line<br />
</VirtualHost><br />
add the three lines<br />
SSLEngine on<br />
SSLCertificateFile /etc/ssl/private/server.crt<br />
SSLCertificateKeyFile /etc/ssl/private/server.key<br />
Then save the file and quit.<br />
Finally we restart Apache<br />
# apache2ctl graceful<br />
and test things. Connect to https://yourserver.yourschool.edu/webwork2/mtTestCourse<br />
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). <br />
<br />
Assuming that everything is working, the last thing we do is set things up so that requests to http://yourserver.yourschool.edu/webwork2/ are automatically redirected to https://yourserver.yourschool.edu/webwork2/.<br />
<br />
# gedit default<br />
<br />
In the <br />
<VirtualHost *:80><br />
section just above the line<br />
ScriptAlias /cgi-bin/ /usr/lib/cgi-bin/<br />
add the line<br />
Redirect permanent /webwork2 https://yourserver.yourschool.edu/webwork2<br />
where of course you should edit <code>yourserver.yourschool.edu</code> appropriately.<br />
Then save the file and quit.<br />
Restart Apache<br />
# apache2ctl graceful<br />
and try connecting to http://yourserver.yourschool.edu/webwork2/. The real connection should be through https://yourserver.yourschool.edu/webwork2/.<br />
<br />
==Where to go From Here ==<br />
<br />
You should play around with <code>myTestCourse</code> e.g. click on <code>Library Browser</code> and browse the <code>Problem Library</code> and also the <code>Rochester</code> and <code>Union</code> libraries.<br />
<br />
Look at http://webhost.math.rochester.edu/webworkdocs/docs/courseadmin/usingwebwork<br />
<br />
Read [[Course Administration]] for more information about creating courses.<br />
<br />
Consult [[Category:Administrators]] for other WeBWorK documentation for system administrators.<br />
<br />
-- Main.ArnoldPizer - 15 May 2008 <br /><br />
<br />
[[Category:Installation Manuals]]</div>Xiong Chiamiov