Installation Manual for 2.4 on SUSE Linux Enterprise Server 11

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

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


See also: History of WeBWorK version control


These instructions cover the installation of the SUSE Linux Enterprise Server 11 operating system and WeBWorK 2.4 from scratch. This document should also work with openSUSE 11 (I haven't tried it). Please make changes if you see any inaccuracies.

Contents

Installing SUSE Linux Enterprise Server 11

Download ISO: link

Note: You will need to get an activation key for SUSE Linux Enterprise Server 11.

Burn the ISO onto a DVD. You can use imgburn or any other tool to burn the iso.

Put in the dvd and run the installer. Intallation Instructions.

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 shell

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

> cp .bashrc .bashrc.bak1

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

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

One is command and file name completion. If you are typing (e.g. ch) and hit <tab> bash will complete the command or filename if it is unambiguous (or more precisely it will complete as much as possible). If there are multiple possibilities (as in the case of ch) nothing will happen 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

Preparing SUSE for WeBWorK

yast2 is the control center for SUSE Linux Enterprise Server. You will use that for most of the installation process. Yast2 has a gui you can start up, you need to login as root and then type in yast2.

yast2 can also be run from a terminal window.

Note: We will not use yast2 HTTP Server configuration under Network Services for WeBWorK.

Network Configuration

Goto Network Devices -> Network Settings. Depending on your network change the different options and then press ok.

SSHD Configuration

Goto Network Services -> SSHD Configuration.

Note: See FAQ.

VNC Configuration

Open a command line and type in

> vncserver

Fill in the password and then you can vnc into the machine from any vnc viewer. After you enter your passwords you will see this message, that will be the vnc instance you will connect to.

New 'X' desktop is webwork:1

Firewall

Goto Security and Users -> Firewall

In Firewall goto Allowed Services and under Service to Allow add the following services: HTTP Server, HTTPS Server, Secure Shell Server, VNC Server

Software Installation

Goto Software -> Software Repositories Copy these links and add it to the list of repositories

  1. OSS
  2. Non-oss

After pressing ok then goto Software Management

Next to Filter on the pull down menu select Search (actually it should be the default selection). Enter gcc in the search box and hit Search 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.

Enter apache2 in the search box and hit Search On the right check apache2 and apache2-mod_perl and any other modules you want.

Enter mysql in the search box and hit Search On the right check mysql and mysql-client

Enter cvs in the search box and hit Search On the right check cvs

Finally enter perl in the search box and hit Search On the right check perl-DBD-mysql, perl-GD and perl-MailTools and all the perl modules from this list. The remaining we will install using CPAN.

Now click on Accept in the lower right hand corner and then Continue to accept Automatic Changes Again you can relax as the packages get installed When you see Install or remove more packages click No and then close the YaST window

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 set up CPAN. For this you have to be root.

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

Since this is the first time you are using CPAN it will ask you Are you ready for manual configuration? Respond no and that should be it.

Next we add at least one mirror and reload the index. A list of mirrors can be found at http://mirrors.cpan.org. To add the mirror ftp://mirrors.kernel.org/pub/CPAN and reload the index do the following

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

Note that one time this failed when I tried to do it in the evening but when I tried again the next morning it worked fine. Now we update CPAN itself

cpan> install Bundle::CPAN

and always hit <Enter> to accept the defaults when prompted. This can be a long process with many long pauses. Please be patient. When you again see the

cpan>

prompt enter

cpan> reload cpan
cpan> o conf commit

and finally

cpan> install Email::Address Mail::Sender Data::UUID String::ShellQuote  XML::Parser::EasyTree

and accept all defaults by just hitting <Enter>. Hopefully this last command will be processed very quickly as it was for me. Next

cpan> install Bundle::Apache2  ExtUtils::XSBuilder Net::LDAP

and accept all defaults. Don't worry about problems installing SSLeay. Note that Bundle::Apache2 and Bundle::CPAN are not modules (rather they are bundles of modules) so you can't test if they are installed directly.


When you again see the

cpan>

prompt enter

cpan> exit

Checking Module Dependancies

WeBWorK includes a script called check_modules.pl that verifies that the needed programs and Perl modules are installed on your system. Run this script to make sure you have installed the required programs and Perl modules.

> check_modules.pl apache2

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

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 after exiting CPAN and becoming a normal user

cpan> exit
# exit
>
> 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 http://search.cpan.org/, search for DateTime and click on DateTime. Then near the top right download DateTime-0.36.tar.gz and save it to disk. Move it to your downloads directory. Then

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


> perl Makefile.PL
> make
> make test

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

DateTime requires the additional modules version , Module::Build , Class::Singleton , DateTime::TimeZone and DateTime::Locale . We could install these using CPAN
# perl -MCPAN -e shell
cpan> install version Module::Build Class::Singleton DateTime::TimeZone DateTime::Locale
cpan> exit
# exit
>

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

Assuming all is OK

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

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

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

If you see

installed!

you can celebrate.

TeX

Download the iso from here.

Once downloaded you can mount the iso with this command:

mount -t iso9660 -o ro,loop,noauto /your/texlive2008.iso /mnt

Once mounted cd /mnt and run

# ./install-tl

or

# ./install-t1 -gui

Default settings are fine but make sure symlinks option is on and pointing to /usr/bin

This should take care of Netpbm and dvipng. If not please refer to this link.

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 (e.g. click on the "house" near the lower left --- this gives your home directory , then on downloads and drag the files). 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 http://httpd.apache.org/download.cgi. 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 http://perl.apache.org/download/index.html 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 http://httpd.apache.org/download.cgi. 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 http://perl.apache.org/docs/2.0/user/install/install.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 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 Quit. In your terminal window you will probably have to ^C to get back to the # prompt

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 (note I had to close all Firefox windows and start a new Firefox session for this to work) 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 http://httpd.apache.org/apreq 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. In a 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 (e.g. use Find under Edit to search for Example:)

# 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

and check Apache by connecting to "http://localhost/perl-status" using a browser on your machine. The title line should list mod_apreq2 along with mod_perl.

Now set up things so that Apache starts automatically at boot up.

# cd /etc/init.d
# cp boot.local boot.local.bak1
# kwrite boot.local

and add the line

/usr/local/apache2/bin/apachectl start

to the end of the file. Then save the file and quit.

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

Check that Apache is running 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 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. 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. 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. The following are rather long commands; I would suggest you copy them and paste them into your terminal window rather than typing them.

> cd
> cd downloads

> cvs -d :pserver:cvs.webwork.rochester.edu:/webwork/cvs/system co -r rel-2-4-patches webwork2
> cvs -d :pserver:cvs.webwork.rochester.edu:/webwork/cvs/system co -r rel-2-4-patches pg
> cvs -d :pserver:anoncvs@cvs.webwork.rochester.edu:/webwork/cvs/npl co NationalProblemLibrary

The last download contains the WeBWorK National Problem Library. This now includes the Rochester and Union Libraries. There is quite a bit of overlap between these libraries but now you system is loaded with many thousands of WeBWorK problems.

Installing WeBWorK

WeBWorK is typically installed using CVS. We provide version tags that correspond to each released version of WeBWorK. This ensures that you can maintain a stable system, and experimental upgrades will not be applied to your installation.

We also provide tarballs for each release. They contain the necessary CVS data to update from CVS at a later date. Choose a tarball if for some reason you do not want to use CVS. Keep in mind that because of the layout of files within the webwork2 directory tree, upgrading an existing installation is harder using a tarball than using CVS.

Creating the base directory directory

Before you begin installing files, create a base directory to hold them. We prefer /opt/webwork:

# mkdir -p /opt/webwork

To make things easier during the installation, you can give yourself write permission to this directory. That way, you won't have to become root to install the WeBWorK files:

# chown yourNameHere /opt/webwork

Installing from CVS

Installing from CVS allows you more flexibility in selecting versions of the WeBWorK code between or ahead of releases. You have several options, depending on which release tag you select when accessing the CVS repository.

CVS tags

Released version: By specifying the rel-2-4-1 tag, you get the same version of the code that you would by downloading the WeBWorK 2.4.1 tarball. This is the most conservative option. Updating will have no effect -- this code will never change.

Released version with patches: By specifying the rel-2-4-patches tag, you can stay up to date with the latest bug fixes against the released version of WeBWorK 2.4. Few, if any, new features are introduced on a patch branch. We recommend that you choose this option.

Latest code: If you do not specify a release tag, you will get the latest code. Since this code is a work in progress, it is sometimes unstable or broken. If you require features that are not in a stable release, and are willing to devote more time to keeping your installation running smoothly, this may be the option for you.

No matter what tag you chose, you can change later by specifying a new tag when running cvs upgrade.

New installation from CVS

If you do not have an existing WeBWorK installation, use the following commands to check out copies of the webwork2 and pg modules. If you are prompted for a password, press enter.

Released version:

$ cvs -d :pserver:anoncvs@cvs.webwork.rochester.edu:/webwork/cvs/system checkout -r rel-2-4-1 webwork2
$ cvs -d :pserver:anoncvs@cvs.webwork.rochester.edu:/webwork/cvs/system checkout -r rel-2-4-0 pg

Released version with patches:

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

Latest development code:

$ cvs -d :pserver:anoncvs@cvs.webwork.rochester.edu:/webwork/cvs/system checkout webwork2 pg

The message warning: cannot open /webwork/cvs/system/CVSROOT/val-tags read/write: Permission denied is harmless and should be ignored.

After checkout finishes, become root and move the directories to the your installation directory. I prefer /opt/webwork:

# cp -r webwork2 /opt/webwork/webwork2
# cp -r pg /opt/webwork/pg

Upgrading using CVS

If you already have an existing WeBWorK installation, use the following commands to update your exsting files to version 2.4. You may need to become root to run these commands (depending on your permissions situation).

Take note of the messages that CVS gives during the update. If you have modified files, you may see the message Merging differences between version1 and version2 into _filename_. This indicates that the file in question is updated in WeBWorK 2.4, and since you also made local modifications to it, CVS is attempting to merge the two changed versions.

If this process fails, because the same parts of the file were modified in both versions, you will see the message rcsmerge: warning: conflicts during merge. If you end up in this situation, you will need to resolve the conflict by editing the file in question. Consult this conflicts example from the CVS manual.

The message warning: cannot open /webwork/cvs/system/CVSROOT/val-tags read/write: Permission denied is harmless and should be ignored.

Released version:

cd /opt/webwork/webwork2
cvs  -q update -dP -r rel-2-4-1
cd /opt/webwork/pg
cvs  -q update -dP -r rel-2-4-0

Released version with patches:

cd /opt/webwork/webwork2
cvs -q update -dP -r rel-2-4-patches
cd /opt/webwork/pg
cvs  -q update -dP -r rel-2-4-patches

Latest development code:

cd /opt/webwork/webwork2
cvs  -q update -dPA
cd /opt/webwork/pg
cvs  -q update -dPA

Installing from a tarball

Tarballs of WeBWorK releases are available from our SourceForge file release page. You will need to download both a webwork tarball and a pg tarball. Make sure that the versions of the tarballs match. You can choose either a GZip or BZip2 archive.

After downloading the tarballs, untar them somewhere (like your home directory):

$ tar -xjf webwork-2.4.1.tar.bz2
$ tar -xjf pg-2.4.0.tar.bz2

If you have an existing WeBWorK installation, move your existing webwork2 and pg directories to webwork2.OLD and pg.OLD, respectively. (You will move your existing courses and configuration over to the new directories later.)

Then, become root and move the directories to the your installation directory. The installation directory should not be web-accessible. I prefer /opt/webwork:

# cp -r webwork-2.4.1 /opt/webwork/webwork2
# cp -r pg-2.4.0 /opt/webwork/pg

From now on, we will assume that WeBWorK 2 is installed in /opt/webwork/webwork2 and PG is installed in /opt/webwork/pg.

Installing fonts for jsMath

jsMath is a display mode that renders math expressions using a JavaScript implementation of the TeX math layout engine. For more information about jsMath, see http://www.math.union.edu/~dpvc/jsmath/.

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

$ cd /opt/webwork/webwork2/htdocs/jsMath
$ tar -xzvf 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} hash in global.conf to 1. This will prevent jsMath from using the image fallback methods.

See also: jsMath settings

Creating the courses directory

The courses directory should be located at /opt/webwork/courses. Placing the courses directory outside the webwork2 directory makes updates easier.

You can create your courses directory from the courses.dist directory distributed with WeBWorK. This directory contains the skeleton of a course called modelCourse, which contains the template files for three demo sets. You can opt to copy templates from this set when creating new courses.

$ cd /opt/webwork/webwork2
$ cp -RPp courses.dist ../courses

If you prefer not to use modelCourse, you can create an empty courses directory instead:

$ cd /opt/webwork
$ mkdir courses

If you are upgrading from WeBWorK 2.2.x, move your existing courses into the new /opt/webwork/courses directory.

Making copies of distribution configuration files

Some files are distributed with the .dist suffix. You must make copies lacking the .dist suffix for WeBWorK to be able to find them. This is done to ease updating with CVS. The .dist files may be updated during a CVS update, but your local versions will be left untouched.

Before configuring the system, you must make local copies of the global.conf and database.conf configuration files, located in /opt/webwork/webwork2/conf/:

$ cd /opt/webwork/webwork2/conf
$ cp global.conf.dist global.conf
$ cp database.conf.dist database.conf

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 User and Group Management
  4. Select Groups
  5. Click Add
  6. Under Group Name enter wwdata
  7. Click accept
  8. Then finish
  9. Now select Users
  10. Select yourself and click Edit
  11. Select Details and under groups
  12. Put a check in the box for wwdata
  13. Click accept
  14. Click Set Filter and select System Users
  15. Select daemon (which is really the apache server) and click Edit
  16. Select Details and under groups
  17. Put a check in the box for wwdata
  18. 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 your 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. If you installed WeBWorK in the default location of /opt/webwork/webwork2, add the directory /opt/webwork/webwork2/bin to your path.

if your shell is put this line in this file
bash export PATH=$PATH:/opt/webwork/webwork2/bin ~/.bashrc
tcsh setenv PATH $PATH:/opt/webwork/webwork2/bin ~/.cshrc

Set the WEBWORK_ROOT environment variable. Some command-line scripts rely on this variable to find other WeBWorK files.

if your shell is put this line in this file
bash export WEBWORK_ROOT=/opt/webwork/webwork2 ~/.bashrc
tcsh setenv WEBWORK_ROOT /opt/webwork/webwork2 ~/.cshrc

Configuring WeBWorK

Most WW configuration is done in the file /opt/webwork/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 WW to work with your system. The rest of the file consists of customization options.

Seed variables

These are the main configuration variables of WeBWorK. The are used by the Apache configuration and by the system itself. Many other settings rely on these variables:

variable description
$webwork_url The URL associated with the WeBWorK handler. Usually /webwork2.
$pg_root The path to the PG directory. Usually /opt/webwork/pg.
$webwork_htdocs_url The URL of static WeBWorK hypertext files. Usually /webwork2_files.
$webwork_htdocs_dir The path to the static WeBWorK hypertext files. Usually $webwork_dir/htdocs.
$webwork_courses_url The URL of the courses directory. Usually /webwork2_course_files.
$webwork_courses_dir The path to the courses directory. Usually $webwork_dir/courses.

Paths to external programs

To avoid executing malicious code, WW calls external programs using full path names.

variable description
$externalPrograms{mkdir} Path to mkdir binary. Usually /bin/mkdir.
$externalPrograms{mysql} Path to mysql binary. Usually /usr/bin/mysql or /usr/local/bin/mysql.
$externalPrograms{tar} Path to tar binary. Usually /usr/bin/tar.
$externalPrograms{latex} Path to latex binary. Usually /usr/bin/latex or /usr/local/bin/latex.
$externalPrograms{pdflatex} Path to pdflatex binary. Usually /usr/bin/pdflatex or /usr/local/bin/pdflatex.
$externalPrograms{dvipng} Path to dvipng binary. Usually /usr/bin/dvipng or /usr/local/bin/dvipng.
$externalPrograms{tth} Path to tth binary. Usually /usr/bin/tth or /usr/local/bin/tth.
$externalPrograms{giftopnm} Path to giftopnm binary. Usually /usr/bin/giftopnm or /usr/local/bin/giftopnm.
$externalPrograms{ppmtopgm} Path to ppmtopgm binary. Usually /usr/bin/ppmtopgm or /usr/local/bin/ppmtopgm.
$externalPrograms{pnmtops} Path to pnmtops binary. Usually /usr/bin/pnmtops or /usr/local/bin/pnmtops.
$externalPrograms{pnmtopng} Path to pnmtopng binary. Usually /usr/bin/pnmtopng or /usr/local/bin/pnmtopng.
$externalPrograms{pngtopnm} Path to pngtopnm binary. Usually /usr/bin/pngtopnm or /usr/local/bin/pngtopnm.

Mail settings

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

To send mail, WW needs the address of an SMTP server. When connecting to the SMTP server, it must also send an email address representing the sender of the email.

variable description
$mail{smtpServer} The address of an SMTP server. If the local machine is running an SMTP server (as is likely), use localhost.
$mail{smtpSender} The address to send when connecting to the SMTP server. This has nothing to do with the From address on the mail message.

Database settings

The following settings are used in connecting to the MySQL database.

variable description
$database_dsn The location of the WeBWorK database. Usually dbi.mysql.webwork. See the Perl DBI documentation for more information about DSNs.
$database_username The username to use when connecting to the database. Usually webworkWrite.
$database_password The password to use when connecting to the database. Use a secure, random password of sufficient length.

The $dbLayoutName variable controls the default database layout that will be used for new courses. If you plan to use MoodleIntegration on all new courses, set this to "sql_moodle". Otherwise, leave it set to the default, "sql_single".

You can override the default when creating a new course.

Timezone setting

You can set the local timezone to use when displaying times using the $siteDefaults{timezone} setting. To get a list of timezone names, run:

$ perl -MDateTime::TimeZone -e 'print join "\n", DateTime::TimeZone::all_names'

To get a list of valid timezone "links" (deprecated names), run:

$ perl -MDateTime::TimeZone -e 'print join "\n", DateTime::TimeZone::links'

Links can be shorter and more familiar, but they may be ambiguous.

Display modes

WeBWorK has several techniques for displaying homework problems. Which of these modes is available is controlled by the $pg{displayModes} list. To disable a display mode, comment out its line from the list by inserting a # character at the beginning of the line.

The supported display modes are as follows:

display mode status description
plainText STABLE This mode shows the raw TeX source of mathematics. It is useful for debugging.
formattedText DEPRECATED This mode uses the tth program to represent mathematics as HTML table structures. Output quality depends on the browser. There are typically font problems on the Mac platform.
images STABLE This mode uses the dvipng program to represent mathematics as PNG images. This gives excellent output on all browsers, but uses more bandwidth, as the images must be sent to the client.
jsMath STABLE This mode uses jsMath to display mathematics. The raw TeX is sent to the client, where a JavaScript program displays it. This requires the client to have a decent JavaScript implementation, and can be slow on older machines.
asciimath DEPRECATED This mode converts mathematics to ASCIIMath on the server and uses a <nobpo>JavaScript to convert them to MathML on the client. Requires a Mozilla-based browser or MSIE with the MathPlater plugin.
LaTeXMathML EXPERIMENTAL This mode is a modification of the asciimath mode that skips the intermediate ASCIIMath form. Requires a Mozilla-based browser or MSIE with the MathPlater plugin.

jsMath settings

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

jsMath settings are stored in the $pg{displayModeOptions}{jsMath} hash:

variable description
reportMissingFonts Set to 1 if you want to have a message displayed for students who don't have the TeX fonts installed. The warning will only be shown on the first page they view that used jsMath (and there is a "hide" button that they can use to hide it even on that page). They can use the control panel to disable the warning messages permanently for their computer, if they want, so even if you turn on the warning message, it is not too intrusive.
missingFontMessage 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.
noImageFonts Set to 1 to prevent jsMath from using the image fallback method. This can be useful if you elected not to unpack the jsMath-fonts.tar.gz archive.
processDoubleClicks By default, double-clicking on the math expression will display the TeX source that generated it. If you wish to disable this behavior, set this to 0. (Note that the raw TeX is still available in the page's HTML source.)

Configuring the database

WeBWorK uses a single MySQL database to store course data. By default, this database is named webwork and is accessed by a MySQL user named webworkWrite.

Creating a new database

If this is a new installation, you must create the webwork database:

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

(Replace password with the password you set for $database_password in global.conf.)

Using an existing database

If you already have a webwork database from WeBWorK 2.1.x or 2.2.x, you must run the utility wwdb_check to make sure that it is up-to-date for use with 2.4.x. You should not use this utility if you are upgrading from 2.3.x or an earlier version of 2.4.x. (For example, from 2.4.1 to 2.4.2.)

To run the utility:

$ /opt/webwork/webwork2/bin/wwdb_check

The script will look at the structure of your webwork database, and alert you to missing tables, missing fields, and incorrect field types. You will have the option to fix these problems.

WeBWorK 2.4 requires permision to LOCK TABLES in the webwork database. Use the mysql console to add it:

$ mysql -u root mysql
Password: ***
> GRANT LOCK TABLES ON webwork.* TO webworkWrite@localhost;
> exit;
$

Automated database initialization and upgrade

WeBWorK 2.3.0 introduces an automatic database upgrade system. Rather than manually issuing SQL commands to make changes to the database, or using ad-hoc scripts like wwdb_addgw, there is a single script called wwdb_upgrade that applies any necessary updates. It should be run when creating a new database, and any time you upgrade WeBWorK.

$ /opt/webwork/webwork2/bin/wwdb_upgrade

Add the -v switch to get more information about what the script is doing.

Note: Run wwdb_upgrade till all databases upgrades are made, currently there are 24 updates.

Image depths database

The "images" display mode has the capability to store depth information in a depths table when equation images are generated. The information allows better alignment of images with surrounding text. In previous versions of WeBWorK, the depths table was stored in a separate database, named DvipngDepths. Starting with WeBWorK 2.3.0, it is stored in the webwork database itself.

If you are upgrading an existing installation, and you had set $pg{displayModeOptions}{images}{dvipng_align} to mysql in the old version, you have depths information stranded in your old DvipngDepths database, and existing images will lose access to this information.

The easiest way to solve this is to delete the existing images. This is probably a good idea anyway when upgrading since existing images won't take advantage of rendering improvements, dvipng improvements, etc. To delete the images:

$ /opt/webwork/webwork2/bin/remove_stale_images --days=0 --delete

Configuring Apache

Testing mod_perl

To verify that mod_perl is installed, you can use mod_info to list the installed modules. If mod_info itself is disabled or not installed, you can either install/enable it, or skip this test and check using Apache::Status instead. The process for installing and enabling modules varies by distribution. To configure mod_perl, uncomment the location block <Location /server-info> in your Apache config file (usually httpd.conf or apache.conf). It should look something like this:

<Location /server-info>
   SetHandler server-info
   Order deny,allow
   Deny from all
   Allow from localhost
   Allow from .yourschool.edu
</Location>

You may have to add the Order, Deny, and Allow lines yourself, or there may already be lines there you can customize. Restart Apache (apachectl graceful) and visit http://yourserver.yourschool.edu/server-info. You should see an entry in the list of active modules for mod_perl.

To further test mod_perl, you can install the Perl module Apache::Status. After installing, add the following section to your Apache config file:

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

Restart Apache (apachectl graceful) and visit http://yourserver.yourschool.edu/perl-status. You should see a page listing various information about mod_perl.

Enabling WeBWorK

Once mod_perl is working, Apache must be configured to handle requests for WeBWorK. Apache provides access to WeBWorK through three URL locations:

  • The location that is handled by the Apache::WeBWorK module, usually /webwork2.
  • The location of system-wide resources, usually /webwork2_files.
  • The location of course-specific resources, usually /webwork2_course_files.

WeBWorK ships with an Apache config file that you can include 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 usually /opt/webwork/webwork2. This value is used to read the WeBWorK configuration file and get the rest of the configuration data.

Further down in the file, you may want to customize the directives used to define the association between Apache and WeBWorK. Specifically, you may need to add the following to the <Location> and <Directory> stanzas, to permit access:

Order allow,deny
Allow from all

After editing webwork.apache-config, append the following line to your Apache configuration file:

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

If you are upgrading from a previous version of WeBWorK which did not use the webwork.apache-config file, you will need to remove the WeBWorK-related directives from your Apache configuration.

Then restart Apache and test your configuration:

Experimental support for Apache 2.0.x

If you are using Apache 2.0.x, follow the directions above, with these changes:

Enable the libapreq module by adding the following line to your Apache2 configuration file. Place this line with the other LoadModule lines.

LoadModule apreq_module modules/mod_apreq.so

Use the module Apache2::Status in place of Apache::Status.

Use the file webwork.apache2-config in place of webwork.apache-config.

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 (you can use your Login Name as your Student ID) and
  4. Then click Add Students
  5. 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 since you are logged in as admin) 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.

Install the National Problem Library

First, make sure you have an /opt/webwork/libraries directory:

$ mkdir -p /opt/webwork/libraries

The database problem library can be downloaded from the npl CVS repository.

$ cd /opt/webwork/libraries
$ cvs -d :pserver:anoncvs@cvs.webwork.rochester.edu:/webwork/cvs/npl co NationalProblemLibrary

Since courses will also look for problem libraries at /opt/webwork/libraries/ProblemLibrary, and /opt/webwork/libraries/database_problib For backwards compatibility we'll create symbolic links to:

$ ln -s /opt/webwork/libraries/NationalProblemLibrary /opt/webwork/libraries/ProblemLibrary
$ ln -s /opt/webwork/libraries/NationalProblemLibrary /opt/webwork/libraries/database_problems

Depending on your previous setup you may have to create additional symbolic links from the previous locations of libraries to the current ones. In particular the popular file libraries are now contained in the National Problem Library so you may need links such as

$ ln -s /opt/webwork/libraries/NationalProblemLibrary/Rochester /opt/webwork/libraries/rochester_problib

at least in the short run to keep older set definition files working.

Configure WeBWorK to access the problem library. The settings are in global.conf:

variable description
$problemLibrary{root} Path to NationalProblemLibrary directory. Should be /opt/webwork/libraries/NationalProblemLibrary.
$problemLibrary{version} Version of the problem library database. Should be =2=.
$problemLibrary_db{dbsource} Name of the database. Can usually be left as $database_dsn.
$problemLibrary_db{user} Username to use when connecting to the database. Can usually be left as $database_username.
$problemLibrary_db{passwd} Password to use when connecting to the database. Can usually be left as $database_password.

Run the NPL-update script to populate the database. This script is located in the webwork2/bin directory and may be invoked from anywhere.

$ /opt/webwork/webwork2/bin/NPL-update
Mysql database reinitialized.
Reading in textbook data.
Converting data from tagged pgfiles into mysql.
Number of files processed:
   100   200   300   400   500   600   700   800   900  1000
...
Done.
$ 

There is no need to add symlinks to course templates directory, as is necessary with file based Problem Libraries. It is done automatically.

Where to go from here

Read Course Administration for more information about managing courses.

Read Problem Libraries for information on installing libraries of pre-written WeBWorK problems.

Read Moodle Integration for information on including WeBWorK problem sets in Moodle courses. (Experimental)

Read LDAP Authentication for information about LDAP authentication. (Experimental)

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

FAQ

Slow ssh login time?

Incorrect name server ip can cause the delay, make sure the name server ip under Network Devices -> Network Settings -> Hostname/DNS is correct.