Installation Manual for 2.3 on Debian 3.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 Debain Linux 3.1 operating system and WeBWorK 2.3 from scratch.

They are more detailed (and offer fewer choices) than the general InstallationManualV2pt3 and are aimed at non unix experts. Readers may want to quickly scan InstallationManualV2pt3 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. 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 Debian 3.1 rev5 Linux Operating System

Installation DVD

Obtain the installation DVD/CD set. Connect to [[1]] for information. 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 www.debian.org. wxDownload Fast automatically calculates the MD5 checksums which is convenient. These instructions will assume you have the two installation DVD's but installing from a commercial DVD/CD set or a downloaded CD set should be essentially identical.

Place the first installation DVD in your DVD drive, turn the computer off and then back on, 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. Note that I had to physically turn off the computer off and then turn it back on (not just reboot it) in order for the network card to be recognized by Debian.

You will see a list of options. Use the arrow and <Tab> keys to hit <Enter> to select the appropriate option).

1. Hit <Enter> to boot
2. A succession of pages follow, for each select the obvious option. For example my obvious options are English, United States and American English
3. Your network interface will most likely be set up automatically via DHCP. If this is not true, you will have to enter your machine's static ip address, etc. Instructions on how to do this are not yet written.
4. Now enter the hostname for your system and then
5. Enter the domain name You should be able to accept the defaults.
6. On 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)
7. Now sit back and relax while the installation takes place --- this may take ten minutes or so

Continue Installation

After this finishes the system will eject the DVD and ask you to reboot. Note that again I had to physically turn off the computer off and then turn it back on (not just reboot it) in order for the network card to be recognized. After awhile, you will get back the the installation screen. Select <Ok> to continue.

1. Answer the question concerning the time the hardware clock is set to
2. Select your time zone
3. Enter the password for the root user and confirm it; Do not forget what you enter here
4. Enter yourself as a user
5. Select the location where the Debian packages will be found. Assuming you are installing from DVD/CD's, select cdrom
6. Place the first Debian DVD/CD back in the DVD drive and scan it for index files
7. Place the second Debian DVD/CD in the DVD drive and scan it for index files
8. Continue until you have scanned all of your DVD/CD's and then select <No> to the Scan another CD question
9. Insert the requested DVD (the first one)
10. Select Install packages manually and hit <Enter>

Now sit back and relax as a whole bunch of packages get installed.

1. Select the type of mail configuration appropriate for your server.
2. Select the user who receives root and postmaster mail

That completed the set up of your base Debian system. Select =<Ok>+ to proceed and then login under your user name.

!! %RED% TO BE CONTINUED. Unfortunately Debian does not recognize some of the hardware on the relatively new laptop I'm using as a testbed (this is a common Debian problem). I'll continue these instructions when I have other hardware availavle to use as a testbed.

%ENDCOLOR%

". Next enter the hostname and domain name.

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 --- Success. 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. I would suggest accepting the patches and updates and when they are finished hit Next. If this doesn't work for you abort, select Configure Later and hit Next. Note that once when I accepted the patches CPAN failed to work at all. I reinstalled SUSE and didn't accept the patches and CPAN worked (up to a point --- see below). This may have been coincidential but if you have difficulties, I suggest you reinstall SUSE without patches. These instructions are based on such an installation.

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

Add yourself as a user and (if you want) select Receive 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 Computer and YaST (Administer Settings)
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 Search. Enter gcc in the search box and hit Search
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 enter TeX in the search box and hit Search
4. On the right check te_latex and tetex
5. Enter mysql in the search box and hit Search
6. On the right check mysql and mysql-client
7. Enter cvs in the search box and hit Search
8. On the right check cvs
9. Finally enter perl in the search box and hit Search
10. On the right check perl-DBD-mysql, perl-GD and perl-MailTools
11. Now click on Accept in the lower right hand corner and then Continue to accept Automatic Changes
12. Again you can relax as the packages get installed
13. When you see Install or remove more packages click No and then close the YaST window

Test Browser and Keyboard

After your desktop reappears, click on Firefox and you should be connected to the world (more precisely to [[2]]). Goto [[3]] 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 Favorites, Configure Desktop (Personal Settings) , Peripherals , Keyboard. Now increase the delay time interval and hit Apply.

Terminal Window Notation and Use

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

To open a terminal window click the SUSE toolbar's Start button then Favorites and Terminal Program

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{Mail::Sender}"

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

1. As our first terminal window task open a terminal window and create a downloads directory where we will keep copies of downloaded software.

> mkdir downloads

Installing Additional Software

Now we have to install additional software which is unfortunately not available from the SUSE 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 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
# exit
>

since otherwise the installation of Module::Build may fail.

First we will install Mail::Sender. For this you have to be root.

> su
<root password>
# perl -MCPAN -e "install q{Mail::Sender}"

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

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

If CPAN can't find things and/or complains that the index is out of date (as it did for me) add some mirror(s) and reload the index. A list of mirrors can be found at [[4]]. To add the mirror mirrors.kernel.org/pub/CPAN and reload the index do the following

# perl -MCPAN -e shell  (Note: if you still have the cpan> prompt you can obviously skip this step)
cpan> o conf urllist push mirrors.kernel.org/pub/CPAN
cpan> reload index

Now try again

cpan> install Data::UUID String::ShellQuote  XML::Parser::EasyTree

If some of the modules fail to install as was the case when I tried, update your version of CPAN as follows

cpan> install Bundle::CPAN

and 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

and finally

cpan> install Data::UUID String::ShellQuote  XML::Parser::EasyTree

and hopefully this last command will be processed very quickly as it was for me. Next

cpan> install Bundle::Apache2  ExtUtils::XSBuilder

and accept all defaults. Don't worry about problems installing SSLeay.

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. At one point in time (August 2006), the installation of DateTime using CPAN was broken. Currently (February 2007) 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.

First install DateTime using CPAN

# perl -MCPAN -e shell
cpan> install DateTime

and accept all defaults to install additional required modules. Note that the first time I tried this, the installation failed. I just repeated the command changing nothing and it succeeded --- only God knows why. Since the DateTime installation is so complicated 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.

Now we give the example of installing DateTime from source. Assuming the installation of DateTime above was successful, you can skip this part.

Goto [[5]], 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.

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 [[6]], 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
>

Apache 2 and mod_perl

Unfortunately I was unable to install all necessary Apache2 components when using the SUSE Apache2 and mod_perl packages. Specifically I was unable to install libapreq2. Therefore we will install Apache2 and mod_perl from source.

Download Apache 2.2.4 from [[7]]. You want Unix Source: httpd-2.2.4.tar.gz. First click on the MD5 link and you will get something like

3add41e0b924d4bb53c2dee55a38c09e  httpd-2.2.4.tar.gz

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

Also goto [[8]] and download mod_perl 2.0: Version 2.03 - November 28, 2006 saving it to disk (the file name is mod_perl-2.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 httpd-2.2.4.tar.gz

The result should be identical to the MD5 sum you saved from the official site [[9]]. Don't use the "3add...c09e" 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 httpd-2.2.4.tar.gz and test it.

Now to install Apache with mod_perl we will follow the directions at [[10]]. 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 enough to see the whole perl Makefile.PL ... prefork" line below. This is a good line to copy and paste unless you type very carefully).

> tar -zvxf httpd-2.2.4.tar.gz
> tar -zvxf mod_perl-2.0-current.tar.gz
> cd mod_perl-2.0.3
> perl Makefile.PL MP_USE_STATIC=1 MP_AP_PREFIX=../httpd-2.2.4 MP_AP_CONFIGURE="--with-mpm=prefork"
> 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 Kwrite. Note that you have to be root to edit httpd.conf. # cd /usr/local/apache2/conf # cp httpd.conf httpd.conf.bak1 # kwrite httpd.conf

In the Kwrite edit window search for #ServerName and change #ServerName www.example.com:80 to
ServerName your_server_address

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

Now append the following to the end of the file

<Location /perl-status>
   SetHandler perl-script
   PerlHandler Apache2::Status
   Order deny,allow
   Deny from all
   Allow from localhost
   Allow from .yourschool.edu
</Location>

where of course you should edit yourschool or leave this line out entirely. Then save the file and exit.

Just to be sure you changed what you wanted do run

# diff httpd.conf httpd.conf.bak1

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

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

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

Further test Apache by connecting to "http://localhost/perl-status" using a browser on your machine and you will see a page listing various information about mod_perl.

Next we have to download and install libapreq2. Goto [[11]] and and part way down the page (not on the left) under Downloads, You can download the latest version of libapreq from click on ASF mirror. (installing from CPAN didn't work for me). Download libapreq2-2.08 and make sure to check it's MD5 checksum as above.

Move libapreq2-2.08.tar.gz to your downloads directory and install it as follows. Ina terminal window

> cd
> cd downloads
> tar -zvxf libapreq2-2.08.tar.gz
> cd libapreq2-2.08
> perl Makefile.PL --with-apache2-apxs=/usr/local/apache2/bin/apxs
> make && make test
> su
<root password>
# make install

Now we have to edit the Apache config file one more time to enable libapreq2.

# cd /usr/local/apache2/conf
# kwrite httpd.conf

Find the lines

# Example:
# LoadModule foo_module modules/mod_foo.so
#

and right after them add the line

LoadModule apreq_module modules/mod_apreq2.so

Then save the file and quit. Gracefully restart Apache

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

and check that Apache is running as above.

Configuring MySQL

First become root and install the MySQL database.

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

Start the MySQL service and configure it 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
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.26

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, Leave, Restart Computer).

Start Apache by running the commands

>su
<root password>
# /usr/local/apache2/bin/apachectl graceful
# exit
>

Actually you could use apachectl start but apachectl graceful will restart Apache gracefully if it's already running and will start it if it isn't.

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

This is also a good time to check that you can login your server from a remote location using SSH (non secure telnet and FTP are not allowed but secure SSH and SFTP are). If you are using "SSH Secure Shell" (now called "SSH Tectia"), a popular SSH client for PC's, you will have to add 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 later.

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. [[12]] 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. To do this we have to edit the MySQL configuration file my.cnf . You can use your favorite editor but we will give instructions assuming you are using Kwrite

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

1. Search (using Find under Edit)) for #skip-networking
2. Uncomment this line (i.e. remove the #) so it becomes
   skip-networking

Then save the file and Quit. 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-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.

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

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

> kwrite .bashrc

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

%RED% WARNING. At the present time the check_modules.pl checks for a number of modules (e.g. Apache 1.3 modules,etc) that are not needed so it is really not that useful and the results may just be confusing.%ENDCOLOR%

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

1. Search for $externalPrograms{tar} = "/usr/bin/tar"; and replace this by
   $externalPrograms{tar} = "/bin/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 [[13]] . 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";

We need to set a password that WeBWorK uses when it communicated 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, 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 Quit.

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 user webworkWrite the following permissions for that database.

username	permissions
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, INSERT, UPDATE, DELETE, CREATE, ALTER, DROP, LOCK TABLES ON webwork.* TO webworkWrite@localhost IDENTIFIED BY 'database_password';
mysql> exit
Bye
> 

Replace database_password with the password you set when editing global.conf above.

jsMath Settings

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

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

Configuring Apache

WeBWorK ships with an Apache config file that needs to included in your main Apache config file. 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

Now edit the httpd.conf file # cd /usr/local/apache2/conf/ # kwrite httpd.conf

Append the following line at the end of the file

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

Then save the file and Quit.

Then restart Apache

# /usr/local/apache2/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 original/httpd.confm
> 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

1. 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!
2. Enter the password, check Save changes and then click Take Action!
3. 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)
4. Now at the far right change Permission Level from 0 (a ordinary student) to 10 (an esteemed professor)
5. 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
> kwrite 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 course.

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

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>

You can also star or stop MySQL by using YaST.

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 Start/Stop/Refresh dropdown, select the appropriate action
7. Click Finish

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>

Next we have to edit global.conf.

> cd /opt/webwork/webwork2/conf
> su
Password: <root password>
# kwrite 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
Password: <mysql root password>
mysql> CREATE DATABASE ProblemLibrary;
mysql> GRANT SELECT ON ProblemLibrary.* TO webworkWrite@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
> su
Password: <root password>
# kwrite 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

> 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 [[14]]

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