Installation Manual for 2.2 on SuSE 10.1

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

These instructions cover the installation of the SUSE Linux 10.1 operating system and WeBWorK 2.2 from scratch.

They are more detailed (and offer fewer choices) than the general InstallationManualV2pt2 and are aimed at non unix experts. Readers may want to quickly scan InstallationManualV2pt2 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>, <F6>, 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. apache_1.3.37.tar.gz rather than the more general apache_1.3.xx.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 SUSE 10.1 Linux Operating System

Installation DVD

Obtain the installation DVD/CD set. Connect to http://en.opensuse.org/Download for information. For example you can use BitTorrent to download an ISO image of the installation DVD and then burn your own installation DVD. These instructions will assume you have such a DVD but installing from a commercial Novell DVD/CD set or a downloaded CD set should be essentially identical.

Place the installation DVD in your DVD drive and boot 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. Select Installation
2. Next you will see the Language page. Select English(US) and click Next
3. A succession of pages follow, for each select the obvious option and click Next. For example my obvious options are Accept the license, New Installation, USA and Eastern time zone
4. When you get to the Desktop Selection select KDE (not because it's better than GNOME but because I have to make a choice)
5. On the Installation Settings page 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)
6. Then click Accept, agree to the required licenses and then click Install
7. Now sit back and relax while the installation takes place --- this may take around a half hour

Continue Installation

After this finishes the system will reboot (if it boots from the DVD select Boot from hard disk). After awhile, you will get back the the installation screen.

Enter a hostname and domain name and next enter the passwood for the root user. As the screen says "Do not forget what you enter here".

Next we come to Network Configuration.

1. Under Firewall click on SSH port is blocked and it should change to SHH port is open
2. Next click on Firewall and then Allowed Services
3. Under Services to Allow select HTTP Server and click Add
4. Next select HTTPS Server and click Add
5. Under Allowed Service you should see HTTP Server, HTTPS Server and SSH
6. Now click Accept

Your network interface will most likely be set up automatically via DHCP. If this is true, 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. Click on Network Interfaces
2. Then Edit
3. Check Static Address Setup and enter the IP Address
4. The Subnet Mask is probably OK as it but another possibility may be 255.255.0.0
5. Next click on Hostname and Name Server and enter the required information (at a minimum you have to enter the ip address of Name Server 1)
6. Click OK and then click on Routing and enter the ip address of your Default Gateway
7. Click OK and then Next and Next again
8. This completes the static ip address setup

Now click on Next to exit the Network Configuration page. The next step tests your network setup. Just click Next and hopefully after a short wait you will see Result --- Sucess. If you don't see this click on View Logs which may give you some hint as to what may be the problem.

Click Next to move to the next page and Next again to configure the online update server. This didn't work for me so I aborted, selected Configure Later and hit Next.

On the User Authentication Method accept the default (Local (/etc/passwd)) and hit Next.

Add yourself as a user and (if you want) select Recieve System Mail and/or Automatic Login. If you want to add additional users at this point, click on User Management but you can always do this later. Hit Next.

Skim the Release Notes and hit Next. Almost certainly you will want to accept the Hardware Configuration SUSE detects by just hitting Next.

That's it. The initial part of the installation is finished. Click on Finish. Assuming you selected Automatic Login above you will see your desktop (otherwise log into your own account).

SUSE Software Packages

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

1. Start up YaST
2. Do this by clicking the SUSE toolbar's Start button (the green button in the lower left hand corner)
3. Then System and YaST (Control Center)
4. Enter the <root password>
5. In the YaST window that opens click Software in the left pane and
6. Software Managment to the right
7. YaST takes a moment to inventory what you already have installed and what you can install. Then it opens a window with a search dialog selected

Now we will select the packages we need and install them.

1. Next to Filter on the pull down menu select Selections and then select C/C++ Complier and Tools (don't check the check box as this will select too much)
2. In the right panel, check gcc. This should give you a black check mark which means it is selected for installation. The blue check marks indicate things already installed; leave them checked.
3. Next select Latex, SGML, and XML and on the right check tetex and te_latex
4. Now next to Filter on the pull down menu select Search. Enter mysql in the search box and hit Search
5. On the right check mysql and mysql-client
6. Enter cvs in the search box and hit Search
7. On the right check cvs
8. Finally enter perl in the search box and hit Search
9. On the right check perl-DBD-mysql, perl-GD and perl-MailTools
10. Now click on Accept in the lower right hand corner
11. Again you can relax as the packages get installed
12. When you see Install or remove more packages click No

Test Browser and Keyboard

After your desktop reappears, click on Firefox and you should be connected to the world (more precisely to http://www.novell.com/linux/). Goto http://devel.webwork.rochester.edu/twiki/bin/view/Webwork/InstallationManualV2pt2forSuSE10pt1 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 the SUSE toolbar's Start button then Personal Settings , Peripherals , Keyboard. Now increase the delay time interval and hit Apply.

Installing Additional Software

Now we have to install additional software which is unfortunately not available from the SUSE package system. First we talk about

Terminal Window Notation and Use

To open a terminal window click on the icon that looks like a monitor.

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 "install q{LWP}"

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 unambigious (or more precisely it will complete as much as possible). If there are multiple possibilities (as in the case of ch) nothing will happen 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 shorcut 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><Insert>). However typing yourself using command completion is probably just as fast except if a command has a long list of options.

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

> sudo <command>
root's password: <root 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 the <root 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).

Apache 1.3 and mod_perl

Open a terminal window and create a downloads directory where we will keep copies of downloaded software.

> mkdir downloads

Download Apache 1.3.37 (WeBWorK doesn't yet work with Apache 2) from http://httpd.apache.org/download.cgi. You want Unix Source: apache_1.3.37.tar.gz. First click on the MD5 link and you will get something like

b278f0969a9ccadeb781316e79e3520f  apache_1.3.37.tar.gz

Save this somewhere. We will use this to verify the integrity of the downloaded file. Now download apache_1.3.37.tar.gz (from some apache mirror) and save it to disk.

Also goto http://perl.apache.org/download/index.html and download mod_perl 1.0: Version 1.29 - Oct 7, 2003 saving it to disk (the file name is mod_perl-1.0-current.tar.gz).

Move these two files from the desktop to your downloads directory (e.g. click on the "house" near the lower left --- this gives your home directory , then on downloads and drag the files).

In the terminal window

> cd downloads

and then run

> md5sum apache_1.3.37.tar.gz

The result should be identical to the MD5 sum you saved from the official site http://httpd.apache.org/download.cgi. Don't use the "b278...20f" above. It's unlikely but possible this could have been altered. If the two MD5 sums are not identical, do not proceed. Download a new copy of apache_1.3.37.tar.gz and test it.

Before installing apache we have to install LWP. For this you have to be root.

> su
<root password>
# perl -MCPAN -e "install q{LWP}"

Since this is the first time you are using CPAN it will ask you Are you ready for manual configuration? Respond no but accept all other defaults (just hit <Enter> repeatedly). This takes a while and there may be long delays especially after your first no; please be patient. After this finishes, become a regular user again

# exit
>

Now to install Apache with mod_perl we will follow the directions at http://perl.apache.org/docs/1.0/guide/getwet.html. After executing the individual commands below you will see a lot of output. The output will indicate if there are problems; there shouldn't be any that will affect the installation. We just indicate the commands you need to execute. Specifically do the following (make sure the window in which you are reading these instructions is wide enought to see the whole perl Makefile.PL ... EVERYTHING=1 line below. This is a good line to copy and paste unless you type very carefully).

> tar -zvxf apache_1.3.37.tar.gz
> tar -zvxf mod_perl-1.0-current.tar.gz
> cd mod_perl-1.29
> perl Makefile.PL APACHE_SCR=../apache_1.3.37/src APACHE_PREFIX=/usr/local/apache DO_HTTPD=1 USE_APACI=1 EVERYTHING=1
> make && make test
> su
<root password>
# make install

Now you have to edit the apache configuration file httpd.conf. You can use your favorite editor but we will give instructions assuming you are using nano. Note that you have to be root to edit httpd.conf.

# cd /usr/local/apache/conf
# nano httpd.conf

In the nano edit window search (using <F6> or <^W>) for #ServerName and change #ServerName www.example.com to
ServerName your_server_address

E.g. I would use www.webwork.math.rochester.edu but you have to use your own.

Search for Port 8080 and comment this out changing Port 8080 to
#Port 8080

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

Just to be sure you changed what you wanted do run

# diff httpd.conf httpd.conf.default

If all is well (i.e. diff reports the changes you made and only those) start Apache

# /usr/local/apache/bin/apachectl start
# exit
>

Now test your server by connecting to "http://localhost/" using a browser on your machine and/or to your server from a browser on a remote machine. You should see a page indicating that apache is running.

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 Module::Build is not so

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

yields

installed!

and

> perl -MModule::Build -e 'print "installed!\n"'

yields

Can't locate Module/Build.pm in @INC (@INC contains: 
/usr/lib/perl5/5.8.8/i586-linux-thread-multi /usr/lib/perl5/5.8.8
...

Installing Additional Perl Modules from CPAN

We need to install a number of additional perl modules from CPAN.

Before we begin, as root run

> su
<root password>
# unset LANG

since otherwise the installation of Module::Build may fail. Note that during the installation process you may have to wait several minutes at lines like Fetching with LWP:, Fetching with Net::FTP: and Connecting to .... Now run

# perl -MCPAN -e shell
cpan> install Apache::Request Data::UUID String::ShellQuote Mail::Sender XML::Parser::EasyTree

Hit <Enter> to accept the default until this doesn't work at the line:

Please provide a full path to 'httpd' executable:

For this enter

[] /usr/local/apache/bin/httpd

and then continue to hit <Enter> to accept all defaults. When you again see the

cpan>

prompt enter

cpan> exit

Installing Additional Perl Modules from Source

We still have one more perl module to install, the DateTime module. The bad news is that at the time these instructions are being written, August 2006, the installation of DateTime using CPAN is broken. The good news is that this gives us an opportunity to show you how to install perl modules from source. It's possible that one of the perl modules we installed above will get updated and its installation from CPAN will get broken. If that happens you can follow the procedures outlined here to install the module from source. More likely the problem with installing DateTime from CPAN will get fixed so the first thing you should try is

# perl -MCPAN -e shell
cpan> install DateTime

Assuming this fails (you might want to ^C out of the process), we will proceed to install DateTime from source. Unfortunately DateTime requires the additional modules version , Module::Build , Class::Singleton , DateTime::TimeZone and DateTime::Locale . We can 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.

Now we will install DateTime from source. Goto http://search.cpan.org/, search for DateTime and click on DateTime. Then near the top right download DateTime-0.34.tar.gz and save it to disk. Move it to your downloads directory. Then

> cd 
> cd downloads
> tar -zvxf DateTime-0.34.tar.gz
> cd DateTime-0.34/
> perl Makefile.PL
> make
> make test

If make test indicates something is missing (which shouldn't be the case with DateTime-0.34.tar.gz) you will have to install that. In such a case 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 seach 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
>

Since DateTime is so difficult to install (at least in August 2006) you definitely should test it

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

If you see

installed!

you can celebrate since all required perl modules are installed.

TTH

WeBWorK gives students a choice of several modes for displaying typeset mathematical expressions on the web. Probably the best are the images mode (really dvipng) and the jsMath mode. The asciiMath mode (really MathML) is getting better. An older mode is formattedTexT (really TTH) which typesets TeX as HTML, using tables and other markup as a fall back display method. In order to make this available goto http://hutchinson.belmont.ma.us/tth/, click on TTH distribution, link to download list and Linux executable . Save the file to disk and then move tth_linux.tar.gz to your downloads directory. Then

> cd 
> cd downloads
> tar -zvxf tth_linux.tar.gz
> cd tth_linux/
>su
<root password>
# cp tth /usr/bin/
# exit
>

Configuring MySQL

First become root and install the MySQL database.

>su
<root password>
# mysql_install_db --user=mysql
# exit
>

Now start the MySQL Service and set it up so that it starts at bootup.

1. Open YaST
2. Click System in the left pane
3. Click System Services (Runlevel) in the right pane
4. Click the Expert Mode radio button at the top of the YaST window
5. Select mysql from the scrolling list
6. Under the Set/Reset dropdown in the lower-right corner, choose Enable the Service
7. This should automatically select the appropriate runlevels to use when starting the service so just click Continue
8. Under the Start/Stop/Refresh dropdown, select Start now ...
9. The MySQL service should start so just click OK to acknowledge the message
10. Click Finish
11. Click Yes to save the changes

You can quickly 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 to server version: 5.0.18

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

mysql> 

Enter exit to exit

mysql> exit
Bye
>

Reboot and Test

Now remove your DVD and reboot the system (SUSE Start Button, Log Out..., Restart Computer).

Check that you can start Apache.

> su
<root password>
# /usr/local/apache/bin/apachectl start
# exit
>

and test by connecting to "http://localhost/" using a browser on your machine and/or to your server from a browser on a remote machine. You should see a page 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 right now.

MySQL Security Issuses

As initially set up, MySQL is a very open system. There are anonymous accounts with full privileges for some databases and the root accounts are not password protected. See e.g. http://dev.mysql.com/doc/refman/5.0/en/default-privileges.html for information on this. We recommend removing the anonymous accounts and giving passwords to the root accounts. There are two root accounts, one is root@localhost and the other 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 FROM mysql.user;

You will see a table with four entries. For localhost you will see two Users, root and one with an empty name (the anonymous user). The other listed Host (with the same two users) is the name of your server which we will denote by host_name.

First we will remove the anonymous accounts.

mysql> DELETE FROM mysql.user WHERE User = ;
mysql> FLUSH PRIVILEGES;

Now using the up arrow key repeat the command

mysql> SELECT Host, User FROM mysql.user;

and you should get a table with only two users (both root).

mysql> exit
Bye
>

Now we will assign a password to these root accounts.

> mysqladmin -u root password "newpwd"
> mysqladmin -u root -h host_name password "newpwd"

In the second command, replace host_name with the name of the server host. The double quotes around the password are not always necessary, but you should use them if the password contains spaces or other characters that are special to your command interpreter. 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 SUSE linux system root user. Below we refer to this as <mysql root password>

Finally we secure the MySQL server by disallowing access via TCP/IP.

>su
<root password>
# cd /etc
# cp my.cnf my.cnf.bak1
# nano my.cnf

1. Search (remember <F6> or <^W>) for #skip-networking
2. Uncomment this line (i.e. remove the #=) so it becomes
=skip-networking

Then save the file and exit (^X, <Y> and <Enter> ). And exit from the root account

# exit
>

That's it. Now the only access to the MySQL server is via the mysql.sock file. Test that all is well:

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

You should see

Welcome to the MySQL monitor ...
mysql>

Enter

mysql> exit
Bye
> 

and congratulate yourself. You are now ready for the 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. General instructions can be found in the WeBWorKCVSReadOnly topic but the following will get the job done.

> cd
> cd downloads

> cvs -d :pserver:anoncvs@cvs.webwork.rochester.edu:/webwork/cvs/system checkout -r rel-2-2-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 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.

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/
# 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. Start YaST
2. Select Security and Users
3. Then Group Management
4. Click Add
5. Under Group Name enter wwdata
6. Click accept
7. Then finish

1. Now select User Management
2. Select yourself and click Edit
3. Select Details and under groups
4. Put a check in the box for wwdata
5. Click accept
6. Click Set Filter and select System Users
7. Select nobody (which is really the apache server) and click Edit
8. Select Details and under groups
9. Put a check in the box for wwdata
10. Click accept and then finish

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.

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 nobody

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

> 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

> nano .bashrc

and just above 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 exit (^X, <Y> and <Enter> ).

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

Scroll up and look through the listing. It should find everything. If something is missing, 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.

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
# nano global.conf

1. Search (remember <F6> or <^W>) for $pg_dir = "/opt/pg"; and replace this by
   $pg_dir = "/opt/webwork/pg";
2. Search for $webwork_courses_dir = "$webwork_dir/courses"; and replace this by
   $webwork_courses_dir = "/opt/webwork/courses";
3. Search for $externalPrograms{tar} = "/usr/bin/tar"; and replace this by
   $externalPrograms{tar} = "/usr/tar";

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 goto 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 in time jsMath is probably the prefered default display mode.

1. Search for $pg{options}{displayMode} = "images"; and replace this by
   $pg{options}{displayMode} = "jsMath";

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

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

Database Configuration

There are two accounts, a read-only account "webworkRead" and a read-write account "webworkWrite", that allow WeBWorK to talk to the database server. By default these accounts have empty passwords. We recommend that you set passwords for these accounts in database.conf.

# nano database.conf

Edit the lines

my %sqlParams = (
   usernameRO => "webworkRead",
   passwordRO => "",
   usernameRW => "webworkWrite",
   passwordRW => "",
   debug      => 0,
);

entering passwords, e.g.

my %sqlParams = (
   usernameRO => "webworkRead",
   passwordRO => "password_RO",
   usernameRW => "webworkWrite",
   passwordRW => "password_RW",
   debug      => 0,
);

where of course you should replace password_RO and password_RW by your own passwords.

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

Now become a regular user again

# exit
>

WeBWorK uses a single database, called webwork, for all courses . Create the webwork database using the your database server's command console. Then grant the users webworkRead and webworkWrite the following permissions for that database.

username	permissions
webworkRead	SELECT
webworkWrite	SELECT, INSERT, UPDATE, DELETE, CREATE, ALTER, DROP

To do this do the following:

> mysql -u root -p mysql
Password: <mysql root password>
mysql> CREATE DATABASE webwork;
mysql> GRANT SELECT ON webwork.* TO webworkRead@localhost IDENTIFIED BY 'password_RO';
mysql> GRANT SELECT, INSERT, UPDATE, DELETE, CREATE, ALTER, DROP ON webwork.* TO webworkWrite@localhost IDENTIFIED BY 'password_RW';
mysql> exit
Bye
> 

Replace password_RO and password_RW with the passwords you have set in the %sqlParams hash above.

jsMath Settings

Version 2.0 of jsMath introduced a new fallback method for when the TeX fonts are not available on the student's computer. This uses images of the individual TeX characters in place of the TeX fonts, but this requires a large number of individual character images in a wide range of sizes. 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 long time, so the v= option is used to show you the names as they are unpacked so that you know the command is actually doing something. Once the images are unpacked, jsMath's image mode fallback (the default fallback method) will work properly, and most students will have results as good as they would with the TeX fonts installed. If you do not wish to install the jsMath image fonts (to save space, for example), you should change the value of =noImageFonts in the $pg{displayModeOptions}{jsMath} in global.conf to 1. This will prevent jsMath from using the image fallback methods.

When a student doesn't have the TeX fonts installed, jsMath can display a warning message pointing to the jsMath font download site. Since the image-mode fallback method is of high enough quality, most students will not feel the need to download and install the fonts, so this warning message is disabled by default. (It tended to worry the students, and there is a link to the download page on the control panel that is new in version 2.0 of jsMath). There are several settings in global.conf that control the font warning message. They are stored in the $pg{displayModeOptions}{jsMath} hash.

The first is reportMissingFonts, which can be set to 1 if you want to have the missing font message displayed for students who don't have the TeX fonts installed. The warning will only be shown on the first page they view that used jsMath (and there is a "hide" button that they can use to hide it even on that page). They can use the control panel to disable the warning messages permanently for their computer, if they want, so even if you turn on the warning message, it is not too intrusive.

The second is missingFontMessage, which can be set to an HTML string that will be used for the missing font message (when reportMissingFonts is non-zero). This string will replace the default warning message, and can be used to point to your own page of instructions for getting the fonts, for example, or for using the control panel to disable the warning.

Our advice is to just unpack the archive which will install the jsMath image fonts. You will be happy with the results.

---

Configuring Apache

WeBWorK ships with an Apache config file that needs to included in your main Apache config file. The file is named webwork.apache-config.dist and located in the conf directory. First, copy the file to webwork.apache-config:

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

Then, edit the copy to set the $webwork_dir variable to the path of the directory containing the WeBWorK installation. This is /opt/webwork/webwork2. This value is used to read the WeBWorK configuration file and get the rest of the configuration data.

# nano webwork.apache-config

Now edit the line my $webwork_dir = "/opt/webwork2"; changing it to
my $webwork_dir = "/opt/webwork/webwork2";

Then save the file and exit.

Now edit the httpd.conf file

# cd /usr/local/apache/conf
# nano httpd.conf

and append the following line at the end of the file

Include /opt/webwork/webwork2/conf/webwork.apache-config

Then save the file and exit.

Then restart Apache

# /usr/local/apache/bin/apachectl graceful
# exit
>

and 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 /usr/local/apache/conf
> diff httpd.conf httpd.conf.default
> cd /opt/webwork/webwork2/conf/
> diff global.conf global.conf.dist
> diff database.conf database.conf.dist
> diff webwork.apache-config webwork.apache-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>
# /usr/local/apache/bin/apachectl graceful
# exit
>

---

Create the admin Course

The CourseAdministrationManual 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
#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 and click Add Students
4. Click on Classlist Editor in the left panel again
5. 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 admin this way) and then click Take Action!
6. Enter the password, check Save changes and then click Take Action!
7. 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)
8. Now at the far right change Permission Level from 0 (a ordinary student) to 10 (an esteemed professor)
9. check Save changes and then click Take Action!

At some point you will probably want to hide the admin course and the modelCourse so that they are not listed on the WeBWorK home page. As we noted above the modelCourse 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, correct!!), 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 and modelCourse courses.

> cd
> nano 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 exit. Now copy the file to the admin and modelCourse .

> sudo cp hide_directory /opt/webwork/courses/admin
root's password:<root password>
> sudo cp hide_directory /opt/webwork/courses/modelCourse

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

Starting and Stoping Apache and MySQL

If you make changes to the system, you will have to restart apache before the changes take effect. You also have to manually start apache after rebooting the machine. 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 apache webserver run the command

> sudo /usr/local/apache/bin/apachectl graceful
root's password:<root password>

To stop the apache webserver run the command

> sudo /usr/local/apache/bin/apachectl stop
root's password:<root password>

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
root's password:<root password>

To stop the MySQL server run the command

> sudo /etc/init.d/mysql stop
root's password:<root password>

To restart the MySQL server run the command

> sudo /etc/init.d/mysql restart
root's password:<root 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
root's password:<root password>

Note that if there is only a short time interval since your previous sudo command, you will not be asked to re-enter the root password.

Next we have to edit global.conf.

> cd /opt/webwork/webwork2/conf
> sudo nano global.conf

1. Search (remember <F6> or <^W>) for problemLibrary and replace $problemLibrary{root} = ""; by
   $problemLibrary{root} = "/opt/webwork/libraries/ProblemLibrary";
2. Replace $problemLibrary{version} = "1"; by
   $problemLibrary{version} = "2";
3. Replace $problemLibrary{userSQL} = "webworkRead"; by
   $problemLibrary{userSQL} = $dbLayouts{sql_single}->{password}->{params}->{usernameRO};
4. Replace $problemLibrary{passwordSQL} = ""; by
   $problemLibrary{passwordSQL} = $dbLayouts{sql_single}->{password}->{params}->{passwordRO};

Then save the file and exit.

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

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

Run the installation script making sure you are in the /opt/webwork/libraries/ProblemLibrary directory. This directory contains the files loadDB2 and create_tables2.sql.

> cd /opt/webwork/libraries/ProblemLibrary
> ./loadDB2  <mysql root password>

This has to convert a lot of data so please be patient.

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
> sudo nano global.conf

1. Search (remember <F6> or <^W>) 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",
3. Directly below this line add the line
                 unionLibrary => "Union",
4. Search for macrosPath and scroll down several lines to the line
   $pg{directories}{macros},
5. After this line add the two lines:
   '/opt/webwork/libraries/union_problib/macros',
'/opt/webwork/libraries/union_problib/parserOrientation',

Then save the file and exit.

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

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

> cd /opt/webwork/courses/modelCourse/templates/
> sudo ln -s /opt/webwork/libraries/union_problib/ unionLibrary
root's password:<root 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 the CourseAdministrationManual for more information about creating courses.

Consult the WeBWorKDocs topic for other WeBWorK documentation.

-- Main.ArnoldPizer - 29 Jul 2006 Initial version based on Sam Hathaway's InstallationManualV2pt2