Installation Manual for 2.4 on Ubuntu 7.04

From WeBWorK_wiki
Jump to navigation Jump to search
This article has been retained as a historical document. It is not up-to-date and the formatting may be lacking. Use the information herein with caution.
This deprecated feature should no longer be used, but is still available for reasons of backwards compatibility.

This feature was deprecated in version 2.6. For up-to-date information view Github. 9


See also: History of WeBWorK version control


This is a work in progress. I am in the process of modifying the instructions for installing WeBWorK 2.3 to cover the case of installing WeBWorK 2.4. Daniel A Graham at Duke has kindly contributed some modifications but more changes need to be made. Mostly these involve changing references from 2.3 to 2.4. However, you should not rely on these instructions until this warning message is removed. These instructions remain unfinished, refer to Installation Manual for 2.4 on Ubuntu 8.04 and/or Installation Manual for 2.3 on Ubuntu 7.04 instead

These instructions cover the installation of the Ubuntu Linux 7.04 operating system and WeBWorK 2.3 from scratch.

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

Notation

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

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

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 7.04 Linux Operating System

Installation CD

Obtain the Desktop Edition, Alternate 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 Check here if you need the alternate desktop CD. This CD does not include the Live CD, instead it uses a text-based installer. For example you can use wxDownload Fast or BitTorrent to download ISO images of the installation DVD's and then burn your own installation DVD's. If you download ISO images, make sure that you verify the integrity of the downloaded files by comparing the MD5 checksums of the downloaded files with the MD5 checksums 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.

Place the installation CD in your DVD/CD drive and reboot your computer from the DVD drive. You may have to press <F12> during the boot process to bring up a boot menu which will allow you to select booting from the DVD. Or you many have to edit the BIOS to select the DVD as the first boot device.

You will see a list of options.

  1. If you want hit <F1> to obtain help and see additional boot methods
  2. You can just hit <Enter> to accept the default install method except in the following situation
  3. If your network has DHCP enabled but you want to setup your server with a static IP address, then hit <F6> and on the Boot OPtions line move the cursor before quiet -- and type netcfg/disable_dhcp=true , leave a space before quiet and then hit <Enter>
  4. A succession of pages follow, for each select the obvious option and hit <Enter>. For example my obvious options are English, United States, <No>, U.S English and U.S English
  5. The system will than scan your CD and load various components
  6. 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)
  7. Unless you entered the netcfg/disable_dhcp=true 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 <Enter> to Cancel if you are impatient). Then hit <Enter> to Continue

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

  1. Select Configure network manually
  2. Enter your computer's IP address and Continue
  3. The netask is probably OK as it but another possibility may be 255.255.0.0
  4. Enter the ip address of your gateway router. Ubuntu makes a good guess at this, but your network may be set up differently.
  5. 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)
  6. Enter the name of your server
  7. This completes the static ip address setup

Next comes the Partition disks pages. You should be able to accept the defaults (unless you are dual booting operating systems, etc. but then you are not a novice user and you are on your own for that part)

  1. Select your time zone and wait for the clock to be configured
  2. Enter yourself as a user (with user name and password). Note this account will function partially as the root account so you might want to make want to pick a different username and password than you regularly use.
  3. Now sit back and relax while the installation takes place --- this takes awhile
  4. 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


  1. Choose to set up a network mirror. Select your country and a mirror. In the US I have found that mirrors.kernel.org works well
  2. You should be able to leave the proxy information blank
  3. I chose not to participate in the package usage survey


Continue Installation

After this finishes the system will eject the DVD and ask you to reboot.

  1. Log into your account
  2. Accept any available updates (you will see a popup window). Click install Updates. You will have to enter the <your password> which functions as the <root password> . Follow any instructions, e.g. you may be told to reboot as soon as the installation is completed (to reboot, select System, Quit and then Restart)

Test Browser and Keyboard

After reboot and login, click on Applications, Internet, Firefox Web Browser (or just click on 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_7.04 where you can view this document and, if you want, copy commands that you need (see below).

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 System, Preferences, Keyboard and then increase the delay time interval and hit Close.

Terminal Window Notation and Use

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

To open a terminal window click Applications, Accessories and then select Terminal.

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

# perl -MCPAN -e shell

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

$ cp .bashrc .bashrc.bak1

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

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

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

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

You can copy commands from these instructions (with copy from the Edit dropdown list or ^C) and paste them into a terminal window (with paste from the Edit dropdown list or <Shift> <Ctrl> <V>). However typing yourself using command completion is probably just as fast except if a command is long.

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 root is to use the sudo 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 sudo commands without reentering <your password>. A log of all sudo commands is kept (I don't know where). In these instructions for the most part we will not use sudo, but keep it in mind for other times that you have to become root in order to execute a few commands (e.g. restarting apache).

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

For our next terminal window task create a downloads directory where we will keep copies of downloaded software. We want to do this as a regular user so first we exit the root account. 

$ cd
$ mkdir downloads

Ubuntu Software Packages

Our next task is to install a number of Ubuntu software packages.

  1. Select System, Administration and then Synaptic Package Manager. You will have to enter the <your password>. The Synaptic Package Manager window will open

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 libapache-authnetldap-perl and then just give the list of required packages.

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

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

  1. apache2
  2. apache2-mpm-prefork
  3. cvs
  4. dvipng
  5. libapache-authnetldap-perl
  6. libapache2-request-perl
  7. libdatetime-perl
  8. libdbd-mysql-perl
  9. libemail-address-perl
  10. libextutils-xsbuilder-perl
  11. libgd-gd2-perl
  12. libmail-sender-perl
  13. libossp-uuid-perl
  14. libstring-shellquote-perl
  15. libtimedate-perl
  16. libxml-parser-perl
  17. libxml-writer-perl
  18. mysql-server-5.0
  19. netpbm
  20. openssh-server
  21. preview-latex-style
  22. tetex-bin
  23. tetex-extra

When I do this I see on the bottom of Synaptic Package Manager window 54 to install/upgrade (note that I didn't install libapache-authnetldap-perl separately; if you did your number will differ). Now click Apply and Apply again to confirm the changes. You will be prompted to insert the CD. After the packages are successfully installed, you can close the Synaptic Package Manager and remove your CD.


That completes the set up of your base Ubuntu system.

Installing Perl Modules

We now have to install one additional Perl module (XML::Parser::EasyTree) which is unfortunately not available from the Debian package system.

Testing Perl Modules

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

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

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

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

yields 

installed!

and 

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

yields 

Can't locate XML/Parser/EasyTree.pm in @INC (@INC contains: 
/etc/perl /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 Are you ready for manual configuration? Respond no 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. 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 (^C) and pasting (<Shift> <Ctrl> <V>) 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 <Enter> 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 XML::Parser::EasyTree 

cpan> install XML::Parser::EasyTree Iterator Iterator::Util Mime::Parser 
cpan> install Net::IP Soap SQL::Abstract XMLRPC::Lite

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

When you again see the 

cpan>

prompt enter 

cpan> exit
#

Installing Additional Perl Modules from Source

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

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

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

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

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


$ perl Makefile.PL
$ make
$ make test

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

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

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

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

Assuming all is OK 

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

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

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

If you see 

installed!

you can celebrate.


Apache 2 and mod_perl

First we have to enable a couple apache modules. Acting as root in a terminal enter # a2enmod apreq # a2enmod info

Next we make a copy of the apache configuration file for safekeeping. # cd /etc/apache2/ # cp apache2.conf apache2.conf.bak1

Next we will edit the apache configuration file apache2.conf to allow us to view information about the setup and performance of the web server. Note that this is not absolutely necessary but it can be very useful. You can use your favorite editor but we will give instructions assuming you are using gedit. Note that you have to be root to edit apache2.conf. # cd /etc/apache2/ # gedit apache2.conf

In the gedit edit window near the end of the file uncomment (i.e. remove the # 's from) the operational lines below. Leave the obvious comment lines (# Allow server status reports ... domain to enable. and # Allow remote server configuration reports... domain to enable.) commented.

The original lines are 

#<IfModule mod_status.c>
    #
    # Allow server status reports generated by mod_status,
    # with the URL of http://servername/server-status
    # Change the ".example.com" to match your domain to enable.
    #
    #<Location /server-status>
    #    SetHandler server-status
    #    Order deny,allow
    #    Deny from all
    #    Allow from .example.com
    #</Location>
#</IfModule>

#<IfModule mod_info.c>
    #
    # Allow remote server configuration reports, with the URL of
    #  http://servername/server-info (requires that mod_info.c be loaded).
    # Change the ".example.com" to match your domain to enable.
    #
    #<Location /server-info>
    #    SetHandler server-info
    #    Order deny,allow
    #    Deny from all
    #    Allow from .example.com
    #</Location>
#</IfModule>

Now in both places replace Allow from .example.com by Allow from localhost. If in addition you want to allow access to server information from e.g. your department domain, add new lines Allow from .math.yourschool.edu below the two Allow from lines where of course you should edit .math.yourschool.edu appropriately. The code (except for yourschool) should look like 

<IfModule mod_status.c>
    #
    # Allow server status reports generated by mod_status,
    # with the URL of http://servername/server-status
    # Change the ".example.com" to match your domain to enable.
    #
    <Location /server-status>
        SetHandler server-status
        Order deny,allow
        Deny from all
        Allow from localhost
        Allow from .math.yourschool.edu
    </Location>
</IfModule>

<IfModule mod_info.c>
    #
    # Allow remote server configuration reports, with the URL of
    #  http://servername/server-info (requires that mod_info.c be loaded).
    # Change the ".example.com" to match your domain to enable.
    #
    <Location /server-info>
        SetHandler server-info
        Order deny,allow
        Deny from all
        Allow from localhost
        Allow from .math.yourschool.edu
    </Location>
</IfModule>

Then save the file and quit (Save and File, Quit).

Just to be sure you changed what you wanted do run 

# diff apache2.conf apache2.conf.bak1
# exit
$

diff should report the changes you made and only those.

Now we have to set your server's fully qualified domain name.

  1. Select System, Administration, Network
  2. Enter <your password>
  3. Click on Hosts
  4. Select the entry with IP Address 127.0.0.1 and click Properties
  5. Under Aliases first enter your server's fully qualified domain name, something like your_server_name.department.school.edu
  6. Next separated by a space or newline enter localhost
  7. And finally, again separated by a space or newline, enter your_server_name (it's important that localhost comes first)
  8. Note that localhost is already listed in which case you only have to enter your server's fully qualified domain name as the first entry and your_server_name as the last entry
  9. Then click OK

There should also be an entry with your server's IP address (if not you should add one)

  1. Select the entry with your server's IP address and click Properties
  2. Under Aliases you should see first your server's fully qualified domain name, something like your_server_name.department.school.edu
  3. And next, separated by a space or newline, your_server_name
  4. Add or edit these entries if they are not correct
  5. Then click OK
  6. And click Close to close Network settings

You can check these settings by running the commands 

$ hostname --fqdn

and 

$ hostname

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

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 Index of / indicating that apache is running.

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

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

Server Version: Apache/2.2.3 (Ubuntu) mod_apreq2-20051231/2.6.0 mod_perl/2.0.2 Perl/v5.8.8

indicating that both mod_apreq2 and mod_perl are installed.

Checking MySQL

First check that MySQL is running by 

$ mysql -u root

You should see 

Welcome to the MySQL monitor.  Commands end with ; or \g.
Your MySQL connection id is 1
Server version: 5.0.38-Ubuntu...

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

mysql>

Enter exit to exit 

mysql> exit
Bye
$

Reboot and Test

Now reboot the system (System, Quit, Restart).

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 Index of / 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 Keyboard Interactive to the list of "Authentication methods" under "Authentication" if it's not already there.

Finally test that MySQL is running. 

$ mysql -u root
...
mysql> 
mysql> exit
Bye
$

Currently the MySQL password is empty so we didn't need a password. We will take care of that now.


MySQL Security Issuses

As initially set up, MySQL is an open system. 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 giving passwords to the root accounts. There are three root accounts, one is root@localhost, one is root@127.0.0.1 and the third is root@host_name where host_name is the name of your server. To find this name, do the following 

$ mysql -u root
mysql> SELECT Host, User, Password FROM mysql.user;

You will see a table with four entries. For localhost you will see two Users, root and debian-sys-maint. The other listed Host (with only the root user) is the name of your server which we will denote by host_name. Now we will assign a password to these root accounts.

In the second command below, replace host_name with the name of the server host. In both commands replace newpwd with your choosen MySQL root password. As was said above, "Do not forget what you enter here". Also remember that this is the password for the MySQL root user, not the Debian linux system root user. Below we refer to this as <mysql root password> 

mysql> UPDATE mysql.user SET password=PASSWORD('newpwd') WHERE host='localhost' and user='root';
mysql> UPDATE mysql.user SET password=PASSWORD('newpwd') WHERE host='127.0.0.1' and user='root';
mysql> UPDATE mysql.user SET password=PASSWORD('newpwd') WHERE host='host_name' and user='root';
mysql> FLUSH PRIVILEGES;

Now use your up arrow key to run the command 

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

and you should see that all three users now have passwords (which will be displayed in encrypted form).

Then exit MySQL 

mysql> exit
Bye
$


and test that all is well: 

$ sudo /etc/init.d/mysql restart
password:<your password>
$ mysql -u root -p 
Enter Password: <mysql root password>

You should see 

Welcome to the MySQL monitor ...
mysql>

Enter mysql> SELECT Host, User, Password FROM mysql.user; 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 localhost account, not to the host_name account but setting a password for the host_name account is a safer thing to do in case the set up gets changed. Now exit MySQL mysql> exit Bye $ and 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 (^C) them from this document and paste (<Shift> <Ctrl> <V>) them in a terminal window 

$ cd
$ cd downloads

$ cvs -d :pserver:anoncvs@cvs.webwork.rochester.edu:/webwork/cvs/system checkout -r rel-2-3-dev webwork2 pg
$ cvs -d :pserver:anoncvs@cvs.webwork.rochester.edu:/webwork/cvs/rochester checkout rochester_problib 
$ cvs -d :pserver:anoncvs@cvs.webwork.rochester.edu:/webwork/cvs/union checkout union_problib
$ cvs -d :pserver:anoncvs@cvs.webwork.rochester.edu:/webwork/cvs/asu checkout database_problems

The first download gives you the latest released version with patches (don't be misled by the dev extension --- this is not a development version). The last download contains the WeBWorK National Problem Library. This now includes the Rochester and Union Libraries along with others but some people still find it convenient to use the Rochester and Union Libraries separately. 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 alone).


Installing WeBWorK

Move the System into the Required Directories

As root create a webwork directory under /opt and move directories there. 

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

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

# mkdir /opt/webwork/courses
# mkdir /opt/webwork/libraries
# mv database_problems/ /opt/webwork/libraries/
# mv rochester_problib/ /opt/webwork/libraries/
# mv union_problib/ /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 writeable 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 writeable 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 DATA, courses, htdocs/tmp, logs, and tmp. It is convenient to give WeBWorK administrators access to these directories as well, so they can perform administrative tasks such as removing temporary files, creating and editing courses from the command line, managing logs, and so on. We will create a new group called wwdata, containing both the WeBWorK administrators and the web server.

  1. Select System, Administration and then Users and Groups
  2. Enter <your password> if requested
  3. Select Manage Groups
  4. Click Add Group
  5. For Group name enter wwdata
  6. Under Group Members select yourself and click OK
  7. Click Close

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 wwdata group as above.

Unfortunately there is a bug (see https://bugs.launchpad.net/ubuntu/+source/gnome-system-tools/+bug/124993) that prevents us from using the Group Manager to add the Apache2 webserver (which runs as www-data) to the wwdata group so we will do this by hand. 

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


  1. In the gedit window scroll to the last line.
  2. It should look like =wwdata:x:1001:<your userid>
  3. Append to this line ,www-data
  4. Then Save and Quit


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

# exit
$ id <your userid>

and then you should see wwdata listed under groups. Also 

$ id www-data

should show wwdata listed under groups. Now we make the WeBWorK directories that need to be writable by the web server have wwdata as their group. The following are rather long commands; you might want to copy them and paste them into your terminal window rather than typing them. 

$ su
<root password>
# cd /opt/webwork/webwork2/
# chgrp -R wwdata DATA ../courses htdocs/tmp logs tmp
# chmod -R g+w DATA ../courses htdocs logs tmp
# find DATA/ ../courses/ htdocs/ 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 bin directory to your path. This will allow you to run WeBWorK command-line utilities without typing the full path to the utility. Goto your home directory and backup your .bashrc file 

$ cd
$ cp .bashrc .bashrc.bak1

Now edit .bashrc 

$ gedit .bashrc

After the last line add the 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 check_modules.pl that verifies that the needed programs and Perl modules are installed on your system. Run this script to make sure you have installed the required programs and Perl modules. 

$ check_modules.pl apache2

Scroll up and look through the listing. It should find everything except PHP::Serialization which is only required if you plan to use WeBWorK with Moodle and tth which is a deprecated display mode. If something is missing (flagged by **), look back through these instructions to find where it should have been installed and install it.

Configuring WeBWorK

Making Copies of the Distribution Configuration Files

Before configuring the system, you must make local copies of the global.conf and database.conf configuration files, located in /opt/webwork/webwork2/conf/ . Since these are owned by root 

$ 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 /opt/webwork2/conf/global.conf. This file provides system-wide configuration settings, and defaults for course settings. Any setting in this file can be overridden in the course.conf file for a particular course. To override a setting for a course, just put the new setting (using the same syntax as is in global.conf) in the course.conf= 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 global.conf 

# 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 DateTime::TimeZone::America::New_York and you should replace $siteDefaults{timezone} = ""; by $siteDefaults{timezone} = "America/New_York";

  1. Search for $siteDefaults{timezone} = ""; and enter your local timezone.

At this point TtH is a deprecated display mode which we didn't install so we have to remove it from the listof possible display modes.

  1. Search for formattedText and comment out the line = "formattedText", # format math expressions using TtH=

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.

  1. Search for $database_password = ""; and replace this by
    $database_password = "database_password";

where of course you should replace 'database_password' with your own password. Remember this password as we will need it below.

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

To send mail, WeBWorK needs the address of an SMTP server. Normally you will use the address of your school's SMTP server. If the local machine is running an SMTP server, use localhost. IMPORTANT: Our instructions above did not install an SMTP server so you will have to install and 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 From address on the mail message).

  1. Edit the lines $mail{smtpServer} = 'mail.yourschool.edu'; and
  2. $mail{smtpSender} = 'webwork@yourserver.yourschool.edu';

entering the appropiate 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 where you should use 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 to the addresses of professors of each course.

Then save the file and Quit.


Now become a regular user again 

# exit
$

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

To do this do the following (before you just copy, paste and hit <Enter> notice that you have to replace database_password with the password you set when editing global.conf 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 database_password with the password you set when editing global.conf above.

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 wwdb_addgw, there is a single script called wwdb_upgrade 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

jsMath Settings

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

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


Configuring Apache

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

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

and now link it into your Apache configuration process 

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

Then restart Apache 

# apache2ctl graceful

If this doesn't work and you see the error 

Syntax error on line 29 of /opt/webwork/webwork2/conf/webwork.apache2-config:
$parms->add_config() has failed: Option FollowSymLinks not allowed here at /usr/lib/perl5/Apache2/PerlSections.pm line 203.\n

we have to do some more work. If you don't get this error, you can skip this section and go on to Test your configuration. At the time these instructions are being written Ubuntu has packaged mod_perl version 2.0.2 which has a small bug which is fixed in version 2.0.3. However we have a pretty easy work around for version 2.0.2. Edit webwork.apache2-config as follows: 

# cd /opt/webwork/webwork2/conf
# gedit webwork.apache2-config

Replace the end of the file (starting with # Provide access to system-wide resources.) with the section below. What we are doing is commenting out the two Directory blocks within the main Perl block, moving them below (i.e. outside) the main Perl block and then replacing perl variables $webwork_htdocs_dir and $webwork_courses_dir with the actual directories. 

# Provide access to system-wide resources.
# 
push @Alias, [ $webwork_htdocs_url => $webwork_htdocs_dir ];
#$Directory{$webwork_htdocs_dir} = {
#   Order => "allow,deny",
#   Allow => [qw/from all/],
#   Options => "FollowSymLinks",
#   AllowOverride => "None",
#};

# Provide access to course-specific resources.
# 
push @AliasMatch, [ "$webwork_courses_url/([^/]*)/(.*)", "$webwork_courses_dir/\$1/html/\$2" ];
#$Directory{"$webwork_courses_dir/*/html"} = {
#   Order => "allow,deny",
#   Allow => [qw/from all/],
#   Options => "FollowSymLinks",
#   AllowOverride => "None",
#};

# If WeBWorK is on the root, exempt the static directories from being handled
# by Apache::WeBWorK.
# 
if ($webwork_url eq "") {
   $Location{$webwork_courses_url} = { SetHandler => "None" };
   $Location{$webwork_htdocs_url} = { SetHandler => "None" };
}

</Perl>

<Directory /opt/webwork/webwork2/htdocs>
    Allow from all
    AllowOverride None
    Options FollowSymLinks
    Order allow,deny
</Directory>

<Directory /opt/webwork/courses/*/html>
    Allow from all
    AllowOverride None
    Options FollowSymLinks
    Order allow,deny
</Directory>

Then save the file and Quit.

Restart Apache 

# apache2ctl graceful

and all should be well. 

# exit
$

Test your configuration

  1. Test the /webwork2 location by visiting http://yourserver.yourschool.edu/webwork2. You should see the WeBWorK home page with no courses listed. Actually the directory /opt/webwork/courses/ does contain the modelCourse but the modelCourse is not a real course so you will get an error message if you try to log into it. It will be used a as model for setting up other courses. For this reason /opt/webwork/courses/modelCourse/ contains a file named hide_directory and so the modelCourse is not visible.
  2. Test the /webwork2_files location by visiting http://yourserver.yourschool.edu/webwork2_files. You should see the "WeBWorK Placeholder Page".
  3. You cannot test the /webwork2_course_files location until you have created a course.

If Something is Wrong

If something is wrong one of the first things to check is that the config files have been edited correctly (e.g. one time a wrapped line in global.conf caused me problems). A quick way to check this is to do a diff between the edited and distributed versions and check that diff reports the changes you made and only those. 

# 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 http://yourserver.yourschool.edu/webwork2 and should see the WeBWorK home page with Course Adninistration listed at the top. Click on it and login with Username admin and Password admin . This first thing you should do is to click on Password/Email and change admin 's password to something more secure than admin .

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

  1. Click on Classlist Editor in the left panel
  2. Check Add 1 student(s) and click Take Action!
  3. Enter the appropiate information (you can leave the last three items blank) and click Add Students
  4. Click on Classlist Editor in the left panel again
  1. When you enter a new student, by default their Student ID is used as their password. We'll change this now.
  2. Select yourself with a check mark and then check Give new password to Selected users or just check Give new password to All users (as a safely mechanism you can not change the password for the user you are logged in as, currently admin, this way) and then click Take Action!
  3. Enter the password, check Save changes and then click Take Action!
  4. Finally give yourself professor privilges by selecting yourself with a check mark, checking Edit Selected users and then clicking Take Action! (or by just clicking on the "pencil" next to your login name which is a much faster way to edit classlist data for a single user)
  5. Now at the far right change Permission Level from 0 (an ordinary student) to 10 (an esteemed professor)
  6. Check Save changes and then click Take Action!

At some point you will probably want to hide the admin course so that it is not listed on the WeBWorK home page. As we noted above the modelCourse, which is already hidden, is not a real course so you will get an error message if you try to log into it. This is a good reason to hide it. The modelCourse is very useful as a model (hence its name) for setting up other courses. The admin course is used for administering WeBWorK and even though regular users can not log into it (you did change the admin password, didn't you!!), it a little bit cleaner and safer to hide it from prying eyes. To hide a course place a file named hide_directory 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 admin course using the URL http://yourserver.yourschool.edu/webwork2/admin but you will not see a link for it on the WeBWorK home page http://yourserver.yourschool.edu/webwork2 . Let's hide the admin course. 

$ cd
$ gedit hide_directory

Now you don't really have to put any verbiage in the file but I suggest you put: 

Place a file named "hide_directory" in a course or other 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.

Save the file and quit. Now copy the file to the admin course. 

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

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

Starting and Stoping Apache, MySQL and the GNOME desktop GUI

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

Starting and Stoping Apache

You have to run these commands as root.

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

$ sudo apache2ctl graceful
password:<your password>

To stop the apache webserver run the command 

$ sudo apache2ctl stop
password:<your password>

You can also start or stop apache2, listed as Web server (apache2), by using the GUI interface.

  1. Select System, Administration and then Services
  2. Scroll down to Web server (apache2)
  3. If apache2 is running, uncheck its check box and click Close to stop it
  4. If apache2 is stopped, check its check box and click Close to start it

Note that I found using apache2ctl a more robust way to start and stop apache2.

Starting and Stoping MySQL

You have to run these commands as root.

To start the MySQL server run the command 

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

To stop the MySQL server run the command 

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

To restart the MySQL server run the command 

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

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

  1. Select Desktop, Administration and then Services
  2. Scroll down to Database server (mysql)
  3. If mysql is running, uncheck its check box and click Close to stop it
  4. If mysql is stopped, check its check box and click Close to start it

Starting and stopping the GNOME desktop GUI

The GNOME desktop is automatically started when the system boots.

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

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

If you stopped GNOME 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 National Problem Library consists of both WeBWorK problems and methods for searching and selecting problems. Also it contains as sub libraries many of the other standard libraries. Normally this library is referred to as the ProblemLibrary but the downloaded CVS directory for it is named database_problems. So the first thing we do is to link ProblemLibrary to database_problems. 

$ cd /opt/webwork/libraries/
$ sudo ln -s database_problems ProblemLibrary
password: <your password>

Next we have to edit global.conf. 

$ cd /opt/webwork/webwork2/conf
$ su
Password: <root password>
# gedit global.conf
  1. Search for problemLibrary and replace $problemLibrary{root} = ""; by
    $problemLibrary{root} = "/opt/webwork/libraries/ProblemLibrary";

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

#exit
$

We now create a database, called ProblemLibrary, for for the Problem Library. To do this do the following: 

$ mysql -u root -p mysql
Enter password: <mysql root password>
mysql> CREATE DATABASE ProblemLibrary;
mysql> GRANT SELECT ON ProblemLibrary.* TO webworkWrite@localhost;
mysql> exit
Bye
$

Update mysql 

$ NPL-update

This has to convert a lot of data 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 loadDB.pl.

Set up the Rochester and Union Libraries

First we need to edit global.conf one last time 

$ cd /opt/webwork/webwork2/conf
$ su
Password: <root password>
# gedit global.conf
  1. Search for courseFiles{problibs} and scroll down several lines to the line
    # rochesterLibrary => "Rochester",
  2. Uncomment this line (i.e. remove the #) so it becomes

         rochesterLibrary => "Rochester",

  1. Directly below this line add the line

         unionLibrary => "Union",

  1. Search for macrosPath and scroll down several lines to the line
    $pg{directories}{macros},
  2. After this line add the two lines:
    '/opt/webwork/libraries/union_problib/macros',
    '/opt/webwork/libraries/union_problib/parserOrientation',

Then save the file and quit.

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


# exit
$ diff global.conf global.conf.dist

and check that you haven't made any mistakes (e.g. by introducing an inadvertant line break, etc).

We next put links to the Rochester and Union Libraries in the modelCourse so that when we create courses copying templates from the modelCourse, these libraries will be available. Skip this step if you usually only want to use National Problem Library. 

$ cd /opt/webwork/courses/modelCourse/templates/
$ sudo ln -s /opt/webwork/libraries/union_problib/ unionLibrary
password: <your password>
$ sudo ln -s /opt/webwork/libraries/rochester_problib/ rochesterLibrary

Create Your First Actual Course

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

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

and log in either as admin or yourself.

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

Where to go From Here

You should play around with myTestCourse e.g. click on Library Browser and browse the Problem Library and also the Rochester and Union libraries.

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

Read Course Administration for more information about creating courses.

Consult for other WeBWorK documentation for system administrators.

-- Main.ArnoldPizer - 21 June 2007 Initial version based on Sam Hathaway's InstallationManualV2pt3 and contributions from Daniel A Graham at Duke

Retrieved from "https://webwork.maa.org/mediawiki_new/index.php?title=Installation_Manual_for_2.4_on_Ubuntu_7.04&oldid=2649"