View source

{{Historical}}

{{Deprecated|2.6.  For up-to-date information view [[Github]]}}


''See also:'' [[History of WeBWorK version control]]


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

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

== Notation ==

First some short comments on notation we will be using. We will use <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.

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

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.

== Installing the Ubuntu 9.04 Linux Operating System ==

===Installation CD ===
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.

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.

First select <code>English</code> by just hitting <code>&lt;Enter&gt;</code>.

You will see a list of options. 

# If you want hit <code>&lt;F1&gt;</code> to obtain help and see additional boot methods
# You can just hit <code>&lt;Enter&gt;</code> to accept the default install method except in the following situation
# 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>
# 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> 
# The system will than scan your CD and load various components
# 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)
# 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>

'''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
# Select <code>Configure network manually</code>
# Enter your computer's IP address and use <code>&lt;Tab&gt;</code> to select <code>Continue</code>
# The <code>netask</code> is probably OK as it but another possibility may be 255.255.0.0
# Enter the ip address of your gateway router. Ubuntu makes a good guess at this, but your network may be set up differently.
# 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)
# Enter the name of your server
# Enter the domain name for the domain your server sits on (e.g. math.myschool.edu)
# This completes the static ip address setup

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

'''Finish the initial installation'''.
# Enter the hostname of your server
# Now select your time zone and wait for the clock to be configured

===Optional Configurations===

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

'''Optional A''' creates a separate partition 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.

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

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

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

===Partition disks===
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. 

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

# 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> 
# Use the down arrow to select your disk (<code>sda</code>)
# 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>
# On the <code>This is an overview...</code> page select <code>FREE SPACE</code>
# On the <code>How to use this free space</code> page select <code>Create a new partition</code>
# 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.
# On the <code>The maximum size you can use...</code> page enter the size for your root (<code>/</code>) partition and <code>Continue</code>
# Select <code>Primary</code> for the type of the new partition
# Select <code>Beginning</code> for the location of the new partition
# Select <code>/</code> for the Mount point of the new partition and then select <code>Done setting up the partition</code>

Now we repeat the process for the partition which will hold WeBWorK's temporary files.
# On the <code>This is an overview...</code> page select <code>FREE SPACE</code>
# On the <code>How to use this free space</code> page select <code>Create a new partition</code>
# 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>
# Select <code>Logical</code> for the type of the new partition
# Select <code>Beginning</code> for the location of the new partition
# Select <code>Mount point</code> and then hit <code>&lt;Enter&gt;</code>
# Select <code>Enter manually</code> and then hit <code>&lt;Enter&gt;</code>
# For the <code>Mount point for this partition</code> enter <code>/var/www/wwtmp</code> and <code>Continue</code>
# Then select <code>Done setting up the partition</code>

Finally we set up the swap partition
# On the <code>This is an overview...</code> page select <code>FREE SPACE</code>
# On the <code>How to use this free space</code> page select <code>Create a new partition</code>
# 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>
# Select <code>Logical</code> for the type of the new partition
# Select <code>Beginning</code> for the location of the new partition
# Select <code>Use as</code> and then hit <code>&lt;Enter&gt;</code>
# Select <code>swap area</code> and then hit <code>&lt;Enter&gt;</code>
# Then select <code>Done setting up the partition</code>

Finally 
# Review your changes and
# Select <code>Finish partitioning and write changes to disk</code> and then hit <code>&lt;Enter&gt;</code>
# Select <code>Yes</code> to confirm the changes

===Base Installation===
# Now the base installation takes place --- this takes a short time
# 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.
# I responded <code>No</code> to encrypting my home directory
# You can probably leave the HTTP proxy information blank
# Now sit back and relax while a lot of software is installed --- this takes awhile

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

===Continue Installation ===
After this finishes the system will eject the CD and ask you to reboot. 

# Log into your account 
# 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>)

===Test Browser and Keyboard ===

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.  
Goto  
http://webwork.maa.org/wiki/Installation_Manual_for_2.4_on_Ubuntu_8.04
where you can view this document and, if you want, copy commands that you need (see below).

If something is wrong and you are not connected to the web, the first thing to do is check that you entered the correct network information.
# Select <code>System</code>, <code>Administration</code>, <code>Network</code>
# Click on <code>Unlock</code>
# Enter <code>&lt;your password&gt;</code> and click <code>Authenticate</code>
# Select <code>Wired connection</code> and click <code>Properties</code>
# Check that all the entries are correct and edit them if they are not
# Then click <code>OK</code>
# Next click on <code>DNS</code> and check the name server entries and correct if necessary
# Click on <code>Close</code> to close <code>Network settings</code>
Your network connection should start up almost immediately. If you are still having problems it's time to investigate further or seek help.

Here's an aside on keystroke delay and repetition rate.  If you are like me and find the keystroke delay too short (so that you often type "geeet" when you want to type "get"), do the following.  Click <code>System</code>, <code>Preferences</code>, <code>Keyboard</code> and then increase the delay time interval and hit <code>Close</code>.

== Terminal Window Notation and Use ==

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

To open a terminal window click <code>Applications</code>, <code>Accessories</code> and then select <code>Terminal</code>.

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

 # perl -MCPAN -e shell

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

 $ cp .bashrc .bashrc.bak1

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

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

One is command and file name completion.  If you are typing (e.g.
<code>ch</code>) and hit <code>&lt;tab&gt;</code> bash will complete the command or filename if it is
unambiguous (or more precisely it will complete as much as possible).
If there are multiple possibilities (as in the case of <code>ch</code>) nothing will
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
hit <code>&lt;tab&gt;</code> a second time and you will see a list of all possible
completions. E.g. entering <code>ch&lt;tab&gt;&lt;tab&gt;</code> gives a list of possible
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
is very fast and convenient and it also leads to fewer typing errors.

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

You can copy commands from these instructions (with <code>copy</code> from the Edit dropdown list or <code>^C</code>) and paste them into a terminal window
(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).

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
manually set a password for the root user since this is a much more standard setup. To do this, type in the following in a terminal window:

 $ sudo passwd
 Password: <your password>

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

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

To test this 

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

Finally perhaps a safer way to run commands as <code>root</code> is to use the <code>sudo</code> command

 $ sudo <command>
 Password: <your password>

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 in <code>/var/log/auth.log</code> .  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>).

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

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

 $ cd
 $ mkdir downloads

==Ubuntu Software Packages ==

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

# 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
# Click on <code>Reload</code> to bring the package information up to date

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

# Select <code>Search</code> 
# Under <code>Look in:</code> select <code>Name</code>. The default <code>Description and Name</code> sometimes returns too many possibilities
# 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>
# 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.
# Follow this basic procedure for all the packages listed below

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

# <code>apache2</code>
# <code>apache2-mpm-prefork</code>
# <code>cvs</code>
# <code>dvipng</code>
# <code>gcc</code>
# <code>libapache2-request-perl</code>
# <code>libdatetime-perl</code>
# <code>libdbd-mysql-perl</code>
# <code>libemail-address-perl</code>
# <code>libextutils-xsbuilder-perl</code>
# <code>libgd-gd2-perl</code>
# <code>libmail-sender-perl</code>
# <code>libnet-ldap-perl</code>
# <code>libossp-uuid-perl</code>
# <code>libsql-abstract-perl</code>
# <code>libstring-shellquote-perl</code>
# <code>libtimedate-perl</code>
# <code>libxml-parser-perl</code>
# <code>libxml-writer-perl</code>
# <code>make</code>
# <code>mysql-server-5.0</code>
# <code>netpbm</code>
# <code>openssh-server</code>
# <code>preview-latex-style</code>
# <code>tetex-bin</code>
# <code>tetex-extra</code>
# <code>unzip</code>

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. 
Now click <code>Apply</code> and <code>Apply</code> again to confirm the changes. You will be asked to enter a
<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>

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


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

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

In case you skipped by it, look above for information on the <code>New password for the MySQL "root" user</code>.

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

=== Testing Perl Modules  ===
To test if a Perl module is installed and working on your system, issue the following command, replacing <code>Module</code> with the name of the module:

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

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

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

yields

 installed!

and

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

yields

 Can't locate XML/Parser/EasyTree.pm in @INC (@INC contains: 
 /etc/perl /usr/local/lib/perl/5.8.8 /usr/local/share/perl/5.8.8
 ...

=== Installing Additional Perl Modules from CPAN ===

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

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

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

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

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

Since this is the first time you are using CPAN it will ask you <code>Would you like me to configure as much as possible automatically?</code> 
Respond <code>Yes</code> and that should be it. 

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 .


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.

 cpan> o conf urllist push ftp://mirrors.kernel.org/pub/CPAN
 cpan> reload index

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

 cpan> install Bundle::CPAN

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. 
When you again see the 

 cpan>

prompt enter

 cpan> reload cpan
 cpan> o conf commit

Now install the following modules

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

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

When you again see the 

 cpan>

prompt enter

 cpan> exit
 #

=== Installing Additional Perl Modules from Source ===
At one point in time (August 2006), the installation of <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.  

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

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

Goto  http://search.cpan.org/,
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

 $ cd 
 $ cd downloads
 $ tar -zvxf DateTime-0.36.tar.gz
 $ cd DateTime-0.36/
 
 
 $ perl Makefile.PL
 $ make
 $ make test

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

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

If you see anything that looks suspicious during this process, you can always test to see if the perl module in question was in fact installed.  If it was not installed
try CPAN first and if CPAN fails then install it from source.  The great thing about CPAN (if it works) is that it will trace down and automatically install all required components.  Note that if you get a message indicating that <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.

Assuming all is OK

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

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

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

If you see 

 installed!

you can celebrate.

== Apache 2 and mod_perl ==

First we have to enable a couple Apache modules. Acting as <code>root</code> in a terminal window enter
 
 # a2enmod apreq
 # a2enmod info

Next we make a copy of the configuration files for safekeeping. 
 
 # cd /etc/apache2/mods-available
 # cp info.conf info.conf.bak1
 # cp status.conf status.conf.bak1

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>

 # cd /etc/apache2/mods-available
 # gedit info.conf

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.

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) 
 #    Allow from .example.com
and then replace <code>.example.com</code> by <code>.math.yourschool.edu</code>
where of course you should edit <code>.math.yourschool.edu</code> appropriately. 

Then save the file and quit (<code>Save</code> and  <code>File</code>, <code>Quit</code>).

Now we edit <code>status.conf</code>

 # cd /etc/apache2/mods-available
 # gedit status.conf

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

 ExtendedStatus On
 
Now edit the 
 #    Allow from .example.com
line just as you did for <code>info.conf</code>.
Then save the file and quit
 
Now we have to set your server's fully qualified domain name. Note that if your network was set up automatically via DHCP, your server's fully qualified domain name should already be set up. You can check by running the <code>hostname</code> commands below.

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
 $sudo apt-get install gnome-network-admin

After this is installed

# Select <code>System</code>, <code>Administration</code>, <code>Network</code>
# Click on <code>Unlock</code>
# Enter <code>&lt;your password&gt;</code> and click <code>Authenticate</code>
# Click on <code>General</code>
# Under <code>Host name</code> enter <code>your_server_name</code> (if it's not already there)
# Then under <code>Domain name</code> enter your server's domain name, something like <code>department.school.edu</code>

Next
# Click on <code>Hosts</code>
#There should also be an entry with your server's IP address (if not you should add one)
# 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)
# Under Aliases you should see your server's fully qualified domain name, something like <code>your_server_name.department.school.edu</code>
# Add or edit these entries if they are not correct
# Then click <code>OK</code>
# And click <code>Close</code> to close <code>Network settings</code>

You can check these settings by running the commands

 $ hostname --fqdn

and 

 $ hostname

The first respond with the fully qualified domain name and the second with just <code>your_server_name</code>.

If the command <code>hostname --fqdn</code> returns <code>Unknown host</code> do the following:

# Select <code>System</code>, <code>Administration</code>, <code>Network</code>
# Click on <code>Unlock</code>
# Enter <code>&lt;your password&gt;</code> and click <code>Authenticate</code>
# Click on <code>Hosts</code>
# Select the entry with your server's IP address and click <code>Properties</code>
# Under Aliases you should see your server's fully qualified domain name, something like <code>your_server_name.department.school.edu</code>
# Select the entry <code>127.0.0.1</code> and click <code>Properties</code>
# Under Aliases make sure you have the following entries in order
## first your server's fully qualified domain name, something like <code>your_server_name.department.school.edu</code>
## second your server's name, something like <code>your_server_name</code>
## third <code>localhost</code>
# 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>
# Then click <code>OK</code>
# And click <code>Close</code> to close <code>Network settings</code>

Then check again by running the commands

 $ hostname --fqdn

and 

 $ hostname

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

Now restart Apache

 $su
 <root password>
 # apache2ctl graceful
 # exit
 $

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

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

Further test Apache by connecting to
"http://localhost/server-info" using a browser on your machine (or or from a browser on a remote machine in the math.yourschool.edu domain) and you will see a page listing various 
information about Apache. In particular under <code>Server Settings</code> you should see

 Server Version: Apache/2.2.11 (Ubuntu) mod_apreq2-20051231/2.6.0 mod_perl/2.0.4 Perl/v5.10.0
indicating that both <code>mod_apreq2</code> and <code>mod_perl</code> are installed.

If you have problems now or in the future, a good first thing to do is to look at the Apache error log which is located at <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 
<code>^C</code> to break out of <code>tail -f</code> .

== Checking MySQL ==

First check that MySQL is running by 

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

You should see something very similar to

 Welcome to the MySQL monitor.  Commands end with ; or \g.
 Your MySQL connection id is 33
 Server version: 5.0.75-0ubuntu10.2 (Ubuntu)

 Type 'help;' or '\h' for help. Type '\c' to clear the buffer.


Enter <code>exit</code> to exit

 mysql> exit
 Bye
 $

== Reboot and Test ==

Now reboot the system (click on your name in the upper right hand corner, then select <code>Restart</code>).

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

This is also a good time to check that you can login your server from a remote location using SSH (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. 

Finally test that MySQL is running.

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

Now lets check the MySQL users.
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 

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

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

Now exit MySQL

 mysql> exit
 Bye
 $

 

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

== Downloading the WeBWorK System Software and Problem Libraries ==
We are finally at the point where we can start downloading and installing WeBWorK. We will use 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

 $ cd
 $ cd downloads
 
 $ cvs -d :pserver:anoncvs@cvs.webwork.rochester.edu:/webwork/cvs/system checkout -r rel-2-4-patches webwork2 pg
 $ cvs -d :pserver:anoncvs@cvs.webwork.rochester.edu:/webwork/cvs/npl checkout NationalProblemLibrary

The first download gives you the latest released version with patches.
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).

== Installing WeBWorK ==
=== Move the System into the Required Directories ===
As <code>root</code> create a <code>webwork</code> directory under <code>/opt</code> and move directories there.  

 $ su
 <root password>
 # mkdir /opt/webwork
 # mv webwork2 /opt/webwork/
 # mv pg /opt/webwork/

Now create the <code>courses</code> and <code>libraries</code> directories under <code>webwork</code> and copy and move content there.

 # mkdir /opt/webwork/courses
 # mkdir /opt/webwork/libraries
 # mv NationalProblemLibrary /opt/webwork/libraries/
 # cd /opt/webwork/webwork2/courses.dist
 # cp *.lst /opt/webwork/courses/
 # cp -r modelCourse /opt/webwork/courses/

=== Setting Permissions ===

The PG installation directory and files should be owned by root and not writable by other users:

 # cd /opt/webwork/pg
 # chown -R root:root .
 # chmod -R u+rwX,go+rX .

Most WeBWorK directories and files should also be owned by root and not writable by other users:

 # cd /opt/webwork/webwork2
 # chown -R root:root .
 # chmod -R u+rwX,go+rX .

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.

# Select <code>System</code>, <code>Administration</code> and then <code>Users and Groups</code>
# Click on <code>Unlock</code>
# Enter <code>&lt;your password&gt;</code> and click <code>Authenticate</code>
# Select <code>Manage Groups</code>
# Click <code>Add Group</code> 
# For <code>Group name</code> enter <code>wwdata</code>
# Under <code>Group Members</code> select yourself and click <code>OK</code>
# Click <code>Close</code>

If there are other users who will also be administering WeBWorK files,
now is a good time to add them.  And remember to add them to the <code>wwdata</code> group as above. When finished
# Click <code>Close</code> again

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>
group so we will do this by hand.

 # cd /etc
 # cp group group.bak1
 # gedit group

 
# In the gedit window scroll to the last line. 
# It should look like <code>wwdata:x:1001:<your userid></code>
# Append to this line <code>,www-data</code>
# Then Save and Quit



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

 # exit
 $ id <your userid>

and then you should see <code>wwdata</code> listed under groups.  Also

 $ id www-data

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

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

== Configuring the Shell ==

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

Add the WeBWorK <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

 $ cd
 $ cp .bashrc .bashrc.bak1

Now edit <code>.bashrc</code>

 $ gedit .bashrc

After the last line add the two lines:

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

Then save the file and Quit.

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

 $ echo $PATH
 $ echo $WEBWORK_ROOT

== Checking Module Dependancies ==



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.

 $ check_modules.pl apache2

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.

== Configuring WeBWorK ==

=== Making Copies of the Distribution Configuration Files ===

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>

 $ su
 <root password>
 # cd /opt/webwork/webwork2/conf
 # cp global.conf.dist global.conf
 # cp database.conf.dist database.conf

=== Global Configuration ===

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.

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>

 # cd /opt/webwork/webwork2/conf
 # gedit global.conf

WeBWorK uses the DateTime module.  DateTime is supposed to be able to determine the local timezone itself without you having to enter it but this often fails so it is best to just set it here.  For is a list of timezones recognized by DateTime go to
http://search.cpan.org/dist/DateTime-TimeZone/ . These timezones are more refined than standard timezone usage in that they include switches to daylight savings time (e.g. some parts of a time zone may make the switch and others may not). For example if your server is in the eastern US, on the list you will see <code>DateTime::TimeZone::America::New_York</code> and you should replace <code>$siteDefaults{timezone} = "";</code> by <code>$siteDefaults{timezone} = "America/New_York";</code>  

# Search for <code>$siteDefaults{timezone} = "";</code> and enter your local timezone.

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.  

# Search for <code>formattedText</code> and comment out the line <code>"formattedText", # format math expressions using TtH</code>
so it becomes

 #   "formattedText", # format math expressions using TtH

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.
# Search for <code>$database_password = "";</code>    and replace this by <br /> <code>$database_password = "database_password";</code> 
where of course you should replace 'database_password' with your own password.  Remember this password as we will need it below.

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

To send mail, WeBWorK needs the address of an SMTP server. Normally you will use the address of your school's SMTP server. If the local machine is running an SMTP server, use <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
 $mail{smtpServer}            = 'mail.yourschool.edu'; 
 $mail{smtpSender}            = 'webwork@yourserver.yourschool.edu';

entering the appropriate information.

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

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

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

Then save the file and Quit.


Now become a regular user again

 # exit
 $

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

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

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

where as we said replace <code>database_password</code> with the password you set when editing <code>global.conf</code> above.

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.

 $ /opt/webwork/webwork2/bin/wwdb_upgrade -v

You should see

 ...
 Database is up-to-date at version 23.
 ...

=== jsMath Settings ===

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

 $ su
 <root password>
 # cd /opt/webwork/webwork2/htdocs/jsMath
 # tar vfxz jsMath-fonts.tar.gz

This will unpack the archive.  Since there are 20,000 tiny files, it can take a little while, so the <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.


== Configuring Apache ==
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>:

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

and now link it into your Apache configuration process

 # cd /etc/apache2/conf.d
 # ln -s /opt/webwork/webwork2/conf/webwork.apache2-config webwork.conf

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

 # cd /etc/apache2/
 # cp apache2.conf apache2.conf.bak1
 # gedit apache2.conf

Search for the line
 Timeout 300
and replace it by
 Timeout 1200
Next seach for the lines
     MaxClients          150
     MaxRequestsPerChild   0
Which occur under <code><IfModule mpm_prefork_module></code> and replace them by
 # For WeBWorK a rough rule of thumb is 20 MaxClients per 1 GB of memory
     MaxClients           20
     MaxRequestsPerChild  100
where you should set <code>MaxClients</code> depending on the amount of memory your server has using the above rule of thumb.

Then save the file and quit.

Finally we copy WeBWorK's icon file <code>favicon.ico</code> to Apache's <code>www</code> directory.
 # cp /opt/webwork/webwork2/htdocs/favicon.ico /var/www

Now restart Apache 

 # apache2ctl graceful
 # exit
 $

== Test your configuration ==

# 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.
# Test the <code>/webwork2_files</code> location by visiting <code>http://yourserver.yourschool.edu/webwork2_files</code>. You should see the "WeBWorK Placeholder Page".
# You cannot test the <code>/webwork2_course_files</code> location until you have created a course.

==If Something is Wrong ==
If something is wrong one of the first things to check is that the config files have been edited correctly (e.g. one time a wrapped line in <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.

 # exit
 $
 $ cd /etc/apache2/
 $ diff apache2.conf apache2.conf.bak1
 $ cd /opt/webwork/webwork2/conf/
 $ diff global.conf global.conf.dist
 $ diff database.conf database.conf.dist
 $ diff webwork.apache2-config webwork.apache2-config.dist 

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

 $ su
 <root password>
 # apache2ctl graceful
 # exit
 $

== Create the admin Course ==

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

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

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

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> )
# Click on <code>Classlist Editor</code> in the left panel
# Check <code>Add 1 student(s)</code> and click <code>Take Action!</code>
# Enter the appropiate information (you can leave the last three items blank) and click <code>Add Students</code>
# Click on <code>Classlist Editor</code> in the left panel again

# When you enter a new student, by default their <code>Student ID</code> is used as their password. We'll change this now.
# 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>
# Enter the password, check <code>Save changes</code> and then click <code>Take Action!</code>
# 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)
# Now at the far right change <code>Permission Level</code> from <code>student</code> to <code>professor</code>
# Check <code>Save changes</code> and then click <code>Take Action!</code>

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

 $ sudo cp /opt/webwork/courses/modelCourse/hide_directory /opt/webwork/courses/admin
 password:<your password>


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

== Starting and Stopping Apache, MySQL and the GNOME desktop GUI ==
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>.  
=== Starting and Stopping Apache ===
You have to run these commands as <code>root</code>.

To start or restart (i.e. stop and then start) the <code>apache2</code> webserver run the command 
 $ sudo apache2ctl graceful
 password:<your password>
You can also start <code>apache2</code> by
 $ sudo apache2ctl start
 password:<your password>
and restart it with
 $ sudo apache2ctl restart
 password:<your password>
<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.

To stop the Apache webserver run the command 

 $ sudo apache2ctl stop
 password:<your password>

You can also start or stop apache2, listed as <code>Web server (apache2)</code>, by using the GUI interface.
# Select <code>System</code>, <code>Administration</code> and then <code>Services</code>
# Click on <code>Unlock</code>
# Enter <code>&lt;your password&gt;</code> and click <code>Authenticate</code>
# Scroll down to <code>Web server (apache2)</code>
# If  <code>apache2</code> is running, uncheck its check box and click <code>Close</code> to stop it
# If  <code>apache2</code> is stopped, check its check box and click <code>Close</code> to start it

Another method is to use the <code>init.d</code> script <code>apache2</code>.  Run
 $ sudo /etc/init.d/apache2
 password:<your password>
and you will get a list of allowed commands (<code>start</code>, <code>stop</code>, <code>restart</code>, etc).

Note that in an earlier version of Ubuntu I found using the GUI interface somewhat unreliable.

=== Starting and Stopping MySQL ===
You have to run these commands as <code>root</code>.

To start the <code>MySQL</code> server run the command 

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

To stop the <code>MySQL</code> server run the command 

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

To restart the <code>MySQL</code> server run the command 

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

You can also start or stop MySQL, listed as <code>Database server (mysql)</code>, by using the GUI interface.

# Select <code>Desktop</code>, <code>Administration</code> and then <code>Services</code>
# Click on <code>Unlock</code>
# Enter <code>&lt;your password&gt;</code> and click <code>Authenticate</code>
# Scroll down to <code>Database server (mysql)</code>
# If  <code>mysql</code> is running, uncheck its check box and click <code>Close</code> to stop it
# If  <code>mysql</code> is stopped, check its check box and click <code>Close</code> to start it

=== Starting and stopping the GNOME desktop GUI ===

The GNOME desktop is automatically started when the system boots.  

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

 $ sudo /etc/init.d/gdm stop 
 password: <your password>

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

 $ sudo /etc/init.d/gdm start 
 password: <your password>

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

===Install the National Problem Library ===
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.

Edit <code>global.conf</code>.

 $ cd /opt/webwork/webwork2/conf
 $ su
 Password: <root password>
 # gedit global.conf

Search for <code>problemLibrary</code> and replace <code>$problemLibrary{root}        = "";</code> by <br /> <code>$problemLibrary{root}        = "/opt/webwork/libraries/NationalProblemLibrary";</code> 

Then save the file and quit. And return to a regular user

 #exit
 $

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

 $ cd /opt/webwork/libraries/NationalProblemLibrary
 $ NPL-update

This has to convert a lot of data (over 18000 files) so please be patient; it can take a long time.

If at some time in the future you want to upgrade the Problem Library, the process
is simpler.  Optionally remove the previous copy of the
library, unpack the new copy in the same place, and run NPL-update.

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.

 $ cd /opt/webwork/courses/modelCourse/templates/
 $ sudo ln -s /opt/webwork/libraries/NationalProblemLibrary Library
 password: <your password>

===Set up the Rochester and Union Libraries ===

This step is optional. It creates buttons in the Library Browser which give direct links to the Rochester and Union libraries. If you don't do this, you can find these libraries and others under the <code>NPL Directory</code> button.

First we need to edit <code>global.conf</code> one last time

 $ cd /opt/webwork/webwork2/conf
 $ su
 Password: <root password>
 # gedit global.conf

Search for <code>courseFiles{problibs}</code> and scroll down several lines to the lines
 #      rochesterLibrary =&gt; "Rochester",
 # 	 unionLibrary     =&gt; "Union",
Uncomment these lines (i.e. remove the <code>#</code>) so they become 
       rochesterLibrary =&gt; "Rochester",
       unionLibrary     =&gt; "Union",
Then save the file and quit.

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.

 # exit
 $ cd /opt/webwork/courses/modelCourse/templates/
 $ sudo ln -s /opt/webwork/libraries/NationalProblemLibrary/Union unionLibrary
 password: <your password>
 $ sudo ln -s /opt/webwork/libraries/NationalProblemLibrary/Rochester rochesterLibrary

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>
&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp; <code>'uva-statLibrary'      => "UVA-Stat",</code> <br>
It's easier to just avoid such names.

===Install and Set Up the CAPA Library ===

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

First we download the CAPA Library including required macros.

 $ cd
 $ cd downloads
 $ cvs -d :pserver:anoncvs@cvs.webwork.rochester.edu:/webwork/cvs/rochester checkout rochester_physics_problib

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 and set the group.

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

We need to edit <code>global.conf</code> again

 # cd /opt/webwork/webwork2/conf
 # gedit global.conf

Search for <code>courseFiles{problibs}</code> and scroll down several lines to the line
 #      capaLibrary      => "CAPA",
Uncomment this line (i.e. remove the <code>#</code>) so it becomes 
       capaLibrary      => "CAPA",

Next search for <code>Locations of CAPA resources</code> and, if necessary, edit the four following lines
so that they read as follows (cut and paste is the best way to do this)

 $pg{specialPGEnvironmentVars}{CAPA_Tools}             = "/opt/webwork/CAPA/CAPA_Tools/",        
 $pg{specialPGEnvironmentVars}{CAPA_MCTools}           = "/opt/webwork/CAPA/CAPA_MCTools/",      
 $pg{specialPGEnvironmentVars}{CAPA_GraphicsDirectory} = "$webworkDirs{htdocs}/CAPA_Graphics/",  
 $pg{specialPGEnvironmentVars}{CAPA_Graphics_URL}      = "$webworkURLs{htdocs}/CAPA_Graphics/",  

Then save the file and quit. Note that we are setting up the CAPA macros and graphics so that they can be used by any WeBWorK course on the server.

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>

 $ cd /opt/webwork/courses/modelCourse/templates/
 sudo ln -s /opt/webwork/libraries/rochester_physics_problib/ capaLibrary
 password: <your password>

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
 cd /opt/webwork/courses/myTestCourse/templates/
 sudo ln -s /opt/webwork/libraries/rochester_physics_problib/ capaLibrary
and do the analogous thing for every course that needs access to the CAPA Library.
Then to gain access to the CAPA Library from the course, simply go to the  <code>Library Browser</code> and click on the  <code>CAPA</code> button.

==Create Your First Actual Course ==

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
 $ cd /opt/webwork/webwork2/conf
 $ diff global.conf global.conf.dist

and check that you haven't made any mistakes (e.g. by introducing an inadvertent line break, etc). If there are any mistakes, correct them. Remember that any time you change
<code>global.conf</code>, you must restart the Apache webserver in order for these changes to take effect. 

Since we have edited <code>global.conf</code> extensively and haven't restartes Apache we do so now.
 $ sudo apache2ctl graceful
 password:<your password>

Now log into the <code>admin</code> course ( <code>http://yourserver.yourschool.edu/webwork2/admin</code> ) as yourself or <code>admin</code>   and 
# click on <code>Add Course</code>
# For <code>Course ID</code> enter <code>myTestCourse</code>
# For <code>Course Title</code> enter <code>My Test Course</code>
# Enter your institution
# Leave <code>Add WeBWorK administrators to new course</code> checked
# Add an additional instructor if you wish
# Copy templates from: <code>modelCourse</code> (the default action)
# Select sql_single for the  database layout  (the default action)
# Click on <code>Add Course</code>
# Click <code>Log into myTestCourse</code>

and log in either as <code>admin</code> or yourself.

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

==Test that Things are Working Properly ==

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

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>

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.

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

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 
informational files that are available if you run into problems (normally these files are removed if there are no errors).

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.  

As a final test click on <code>Library Browser</code> on the <code>Main Menu</code>. Click <code>Problem Library </code>
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.

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

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.

If you are new to WeBWorK, you should probably add a regular student to myTestCourse and log in as that student to see what the student interface looks like. It's much simpler than the professor interface.
Click on <code>Classlist Editor</code> on the <code>Main Menu</code>.
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>.
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.

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

===Implement Optional A (wwtmp)===

Now is the time to implement '''Optional A''' if you choose to do so.  Actually you can do this at any time and your active courses will continue to function seemingly without change.  The only change behind the scenes will be that temporary files will be stored in a different location.

First we set the group and permissions for the <code>wwtmp</code> directory

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

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


 # cd /opt/webwork/webwork2/conf
 # cp global.conf global.conf.bak1
 # gedit global.conf

Now edit <code>global.conf</code>.  Find the lines 

 $webworkDirs{htdocs_temp}   = "$webworkDirs{htdocs}/tmp";
 $webworkURLs{htdocs_temp}   = "$webworkURLs{htdocs}/tmp";
and replace them by 
 #$webworkDirs{htdocs_temp}   = "$webworkDirs{htdocs}/tmp";
 #$webworkURLs{htdocs_temp}   = "$webworkURLs{htdocs}/tmp";
 $webworkDirs{htdocs_temp}   = '/var/www/wwtmp';
 $webworkURLs{htdocs_temp}   = '/wwtmp';

Next find the lines 

 $courseDirs{html_temp}   = "$courseDirs{html}/tmp";
 $courseURLs{html_temp}   = "$courseURLs{html}/tmp";
and replace them by 
 #$courseDirs{html_temp}   = "$courseDirs{html}/tmp";
 #$courseURLs{html_temp}   = "$courseURLs{html}/tmp";
 $courseDirs{html_temp}   = "/var/www/wwtmp/$courseName";
 $courseURLs{html_temp}   = "/wwtmp/$courseName";

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.

===Implement Optional B (lighttpd)===

As is the case for '''Optional A''' you can implement '''Optional B''' at any time and your active courses will continue to function seemingly without change.  The only change behind the scenes will be that static images and pages will be served by a light weight web server.

First we install the light weight webserver <code>lighttpd</code>

# Open the <code>Synaptic Package Manager</code> (select <code>System</code>, <code>Administration</code>,   <code>Synaptic Package Manager</code>).   
# Select <code>Search</code> 
# Search for <code>lighttpd</code> and select it
# In the pop up window <code>Mark additional required changes?</code> click <code>Mark</code> to accept the requirements.
# Now click <code>Apply</code> and <code>Apply</code> again to confirm the changes.

You can now quit the <code>Synaptic Package Manager</code>.

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


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

Now edit <code>lighttpd.conf</code>.  

 # gedit lighttpd.conf

Uncomment the line
 #           "mod_status",
so it becomes
            "mod_status",


Apache2 is listening on port 80 so we need an alternate port for lighttp to listen to. Standard alternate ports for this are usually 81, 8000, or 8080. 8080 is the only port that is listed as an official alternate at http://en.wikipedia.org/wiki/List_of_TCP_and_UDP_port_numbers .  Note that in rare cases an installation may block httpd requests to port 8080. If any of your students report that they can not see graphics, they will have to request that access to requests to port 8080 be allowed.

Find the line
 # server.port               = 81
uncomment it and change 81 to 8080 so that it reads 
 server.port               = 8080

Finally uncomment the line
 # status.status-url = "/server-status"
so it becomes
   status.status-url = "/server-status"
Then save the file and quit.

Now restart lighttp

 $su
 <root password>
 # /etc/init.d/lighttpd restart
 # exit
 $
  
Note that you can just run <code>/etc/init.d/lighttpd</code> to get a list of all options.

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

You can check lighttp's status by connecting to
"http://localhost:8080/server-status" using a browser on your machine or from to "http://yourserver.yourschool.edu:8080/server-status" from a browser on a remote machine.

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

Next we configure WeBWorK to take advantage of lighttp.

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

 # cd /opt/webwork/webwork2/conf
 # cp global.conf global.conf.bak2


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

 # gedit global.conf

Find the line
 $webworkURLs{htdocs_temp}   = '/wwtmp'
and replace it by
 #$webworkURLs{htdocs_temp}   = '/wwtmp';
 $webworkURLs{htdocs_temp}   = 'http://yourserver.yourschool.edu:8080/wwtmp';

Find the line
 $courseURLs{html_temp}   = "/wwtmp/$courseName";
and replace it by
 #$courseURLs{html_temp}   = "/wwtmp/$courseName";
 $courseURLs{html_temp}   = "http://yourserver.yourschool.edu:8080/wwtmp/$courseName";

Then save the file and quit.

Now restart apache and lighttp.

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

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 8080 (something like <code>http://yourserver.yourschool.edu:8080/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 8080.

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

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

We will create and work in a <code>tmp</code> directory.

 $ cd
 $ mkdir tmp
 $ cd tmp

First we create an RSA Private Key.

 $ openssl genrsa -des3 -out server.key 1024

When you are asked for a <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
 $ openssl req -new -key server.key -out server.csr

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 
 A challenge password []:
 An optional company name []:
blank.

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

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

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

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

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

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

Next we enable the <code>mod_ssl</code> module
 # a2enmod ssl

Now we have to configure Apache to use SSL.
 # cd /etc/apache2/sites-available/
 # cp default default.bak1
 # gedit default

Replace the first line
 NameVirtualHost *
by the two lines
 NameVirtualHost *:80
 NameVirtualHost *:443
Now edit the next non blank line
 <VirtualHost *>
changing it to
 <VirtualHost *:80>
Next copy the entire section 
 <VirtualHost *:80> 
 ...
 </VirtualHost>
(that is the whole VirtualHost section to the end of the file) and paste it into the file at the end of the file. Now we edit this new pasted section.
Edit the new second
 <VirtualHost *:80>
changing it to
 <VirtualHost *:443>
Now at the end of the file just above the line
 </VirtualHost>
add the three lines
     SSLEngine on
     SSLCertificateFile /etc/ssl/private/server.crt
     SSLCertificateKeyFile /etc/ssl/private/server.key
Then save the file and quit.
Finally we restart Apache
 # apache2ctl graceful
and test things. Connect to https://yourserver.yourschool.edu/webwork2/myTestCourse
You will be asked to accept the certificate. After you do so things should work just as before except that all the connection will be via https (except for images, etc if you using lighttp). 

Assuming that everything is working, the last thing we do is set things up so that requests to http://yourserver.yourschool.edu/webwork2/ are automatically redirected to https://yourserver.yourschool.edu/webwork2/.

 # gedit default

In the 	
 <VirtualHost *:80>
section just above the line
 	ScriptAlias /cgi-bin/ /usr/lib/cgi-bin/
add the line
 Redirect permanent /webwork2 https://yourserver.yourschool.edu/webwork2
where of course you should edit <code>yourserver.yourschool.edu</code> appropriately.
Then save the file and quit.
Restart Apache
 # apache2ctl graceful
and try connecting to http://yourserver.yourschool.edu/webwork2/.  The real connection should be through  https://yourserver.yourschool.edu/webwork2/.

==Updating WeBWorK files==

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
 $ cd /opt/webwork/webwork2/lib/WeBWorK/Utils
 $ sudo cvs update FilterRecords.pm
If you want to update all files in a directory and in all its subdirectories, run the command 
 $ sudo cvs update 
form the directory.

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
 $ cd /opt/webwork/webwork2/lib/WeBWorK/Utils
 $ sudo mv FilterRecords.pm FilterRecords.pm.old
 $ sudo cvs update FilterRecords.pm
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.

If you want to update the whole WeBWorK system, I would suggest doing the following.
 $ cd /opt/webwork
 $ sudo mv webwork2 webwork2_old
 $ sudo mv pg pg_old
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.

==Where to go From Here ==

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.

Look at http://webhost.math.rochester.edu/webworkdocs/docs/courseadmin/usingwebwork

Read [[Course Administration]] for more information about creating courses.

Consult [[Category:Administrators]] for other WeBWorK documentation for system administrators.

-- Main.ArnoldPizer - 15 May 2008 <br />

[[Category:Installation Manuals]]