Installation Manual for 2.4
Contents
- 1 Installation Methods and Instructions
- 2 Installation instructions for specific operating systems
- 3 Dependencies
- 4 Installing the WeBWorK files
- 5 Configuring your shell
- 6 Configuring WeBWorK
- 7 Configuring the database
- 8 Configuring Apache
- 9 Creating the admin course
- 10 Where to go from here
Installation Methods and Instructions
- Installing WeBWorK from a WeBWorK Live DVD (see Installing WeBWorK from a Live DVD ) is the fastest method but offers very few choices (after installation you can make whatever changes you want). You can also run WeBWorK directly off the LiveDVD without installing any software on your system. Finally you can use the .iso image to install WeBWorK as a virtual machine under most modern operating systems (windows, linux, unix, solaris, etc).
- The instructions listed in Installation_Manual_for_2.4#Installation instructions for specific operating systems offer command-by-command procedures (and fewer choices) than the general instructions. They are targeted at UNIX beginners.
- The general instructions on this page offer the most information and choices but are targeted at UNIX experts.
- Installing_WeBWorK_on_Live_USB explains how to download and install a disk image of a fully functioning WeBWorK 2.4 system onto a 2 GB USB flash memory drive. This is suitable for testing WeBWorK and is very convenient if you want to carry your server around on a pen drive.
- Note that the Installation Manual for 2.4 on Ubuntu 10.04 contains information on a number of optional configurations (lighttpd, ssl, CAPA, etc.) and also on updating the WeBWorK system. For that reason, unix experts and others may want to glance at them.
Installation instructions for specific operating systems
These manuals offer command-by-command procedures (and fewer choices) than the general instructions. They are targeted at UNIX beginners.
Dependencies
Apache
WeBWorK supports Apache 1.3 and 2.0. Apache 2.2 is supported experimentally. WeBWorK requires that the mod_alias
module be available. Most vendors compile their Apache packages with the necessary features enabled.
Apache 1.3
- Source: http://httpd.apache.org/
- Debian/Ubuntu:
apache
- Red Hat/Fedora: build from source
Apache 2.0 or 2.2
Apache must be using the prefork
MPM. This is because the Safe
module, which WeBWorK makes extensive use of, is not threadsafe. This is set at compile time with the --with-mpm=prefork
switch to the configure
script.
- Source: http://httpd.apache.org/
- Debian/Ubuntu:
apache2
withapache2-mpm-prefork
- Fedora: check if the
httpd
package provides the right MPM by running/usr/sbin/httpd -l
. Build from source, if not. - Red Hat EL/CentOS/Scientific Linux: in versions 4 and 5,
httpd
uses theprefork
MPM. For other versions, see the Fedora instructions above.
Perl
WeBWorK requires Perl 5.6.1 or higher.
- Source: http://perl.org/
- Debian/Ubuntu:
perl
(in the default install) - Red Hat/Fedora:
perl
(in the default install)
Perl modules
The following Perl modules are required. All are available from CPAN, and many vendors provide packages of these modules. To see if a module is already installed on your system, use the following command. Replace Module
with the name of the module.
$ perl -MModule -e 'print "installed!\n"'
To determine which of the modules used by WeBWorK are already installed run the script:
webwork2/bin/check_modules.pl [apache1|apache2] or perl webwork2/bin/check_modules.pl [apache1|apache2]
which checks for the modules needed for either an apache1 or apache2 installation of WeBWorK respectively. Many of the modules are already installed on most systems.
A nearly comprehensive
list of the CPAN modules needed are listed in the table below, but check_modules.pl
will
be more up to date. For the most part these modules are either already present or can be easily installed using CPAN. Those using compiled binaries for a particular platform may be more quickly and easily installed using packages. Depending on the operating system, packages may also be more easily updated (via OS-specific software upgrade mechanisms) than CPAN modules.
To install a missing module from CPAN, use the following command as root. Replace Module
with the name of the module.
# perl -MCPAN -e "install Module"
For more information about using CPAN, consult the CPAN FAQ.
module | Debian/Ubuntu package | Gentoo package | Fedora Core 7 package | Red Hat EL/CentOS 5 package | FreeBSD port/package |
Apache::Constants | www/mod_perl
| ||||
Apache::Cookie/Apache2::Cookie | perl-libapreq2 from EPEL
|
www/p5-libapreq / www/p5-libapreq2
| |||
Apache::Log | www/mod_perl
| ||||
Apache2::ServerRec | mod_perl
|
www/mod_perl2
| |||
Apache2::ServerUtil | mod_perl
|
www/mod_perl2
| |||
Apache::Request (only if using Apache 1.3.x) |
libapache-request-perl
|
www/p5-libapreq
| |||
Apache2::Request (only if using Apache 2.0.x) |
libapache2-request-perl
|
libapreq
|
perl-libapreq2
|
perl-libapreq2 from EPEL
|
www/p5-libapreq2
|
Data::Dumper | included in perl package
|
lang/perl
| |||
Data::UUID | libdata-uuid-perl (virtual package, provided by libossp-uuid-perl )
|
Data-UUID
|
perl-uuid
|
uuid-perl from EPEL
|
devel/p5-Data-UUID
|
Date::Format and Date::Parse | libtimedate-perl
|
TimeDate
|
perl-TimeDate
|
perl-TimeDate
|
devel/p5-DateTime and devel/p5-DateTime-Format-DateParse
|
DateTime | libdatetime-perl
|
DateTime
|
perl-DateTime
|
perl-DateTime from EPEL
|
devel/p5-DateTime
|
DBD::mysql | libdbd-mysql-perl
|
DBD-mysql
|
perl-DBD-MySQL
|
perl-DBD-MySQL
|
databases/p5-DBD-mysql
|
DBI | perl-DBI
|
databases/p5-DBI
| |||
Digest::MD5 | included in perl package
|
lang/perl
| |||
Email::Address | libemail-address-perl
|
Email-Address
|
perl-Email-Address
|
perl-Email-Address from EPEL
|
mail/p5-Email-Address
|
Errno | included in perl package
|
lang/perl
| |||
Exception::Class | perl-Exception-Class from EPEL
|
devel/p5-Exception-Class
| |||
File::Copy | included in perl package
|
lang/perl
| |||
File::Find | included in perl package
|
lang/perl
| |||
File::Path | included in perl package
|
lang/perl
| |||
File::Spec | included in perl package
|
lang/perl
| |||
File::stat | included in perl package
|
lang/perl
| |||
File::Temp | included in perl package
|
lang/perl
| |||
GD | libgd-gd2-perl
|
GD
|
perl-GD
|
perl-GD from EPEL
|
graphics/p5-GD
|
Getopt::Long | included in perl package
|
lang/perl
| |||
Getop::Std | included in perl package
|
lang/perl
| |||
HTML::Entities | perl-HTML-Parser
|
www/p5-HTML-Parser
| |||
HTML::Tagset | perl-HTML-Tagset
|
www/p5-HTML-Tagset
| |||
IO::File | included in perl package
|
lang/perl
| |||
Iterator | not packaged | not packaged | not packaged | perl-Iterator from Nogin
|
devel/p5-Iterator
|
Iterator::Util | not packaged | not packaged | not packaged | perl-Iterator-Util from Nogin
|
devel/p5-Iterator-Util
|
Mail::Sender | libmail-sender-perl
|
Mail-Sender
|
perl-Mail-Sender
|
perl-Mail-Sender from EPEL
|
mail/p5-Mail-Sender
|
MIME::Parser | perl-MIME-tools from EPEL
|
mail/p5-MIME-Tools
| |||
MIME::Base64 | included in perl package
|
converters/p5-MIME-Base64
| |||
Net::IP | perl-Net-IP
|
net-mgmt/p5-Net-IP
| |||
Net::LDAPS | perl-LDAP
| ||||
Net::SMTP | included in perl package
|
lang/perl
| |||
Opcode | included in perl package
|
lang/perl
| |||
PHP::Serialization | perl-PHP-Serialization from Nogin
|
devel/devel/p5-PHP-Serialization
| |||
Pod::Usage | included in perl package
|
lang/perl
| |||
Safe | included in perl package
|
lang/perl
| |||
SOAP::Lite | perl-SOAP-Lite from EPEL
|
net/p5-SOAP-Lite
| |||
Socket | included in perl package
|
lang/perl
| |||
SQL::Abstract | libsql-abstract-perl
|
unknown | perl-SQL-Abstract
|
perl-SQL-Abstract from EPEL
|
databases/p5-SQL-Abstract
|
String::ShellQuote | libstring-shellquote-perl
|
String-ShellQuote
|
perl-String-ShellQuote
|
perl-String-ShellQuote from EPEL
|
textproc/p5-String-ShellQuote
|
Text::Wrap | included in perl package
|
lang/perl
| |||
Time::HiRes (included in Perl 5.8 and higher) |
included in perl package
|
unknown | included in perl package
|
included in perl package
|
lang/perl
|
Time::Zone | perl-TimeDate
|
devel/p5-DateTime-TimeZone
| |||
URI::Escape | perl-URI
|
net/p5-URI
| |||
XML::Parser | libxml-parser-perl
|
libxml-perl
|
perl-XML-Parser
|
perl-XML-Parser
|
textproc/p5-XML-Parser
|
XML::Parser::EasyTree | not packaged | unknown | not packaged | perl-XML-Parser-EasyTree from Nogin
|
textproc/p5-XML-Parser-EasyTree
|
XML::Writer | libxml-writer-perl
|
XML-Writer
|
perl-XML-Writer
|
perl-XML-Writer from EPEL
|
textproc/p5-XML-Writer
|
XMLRPC::Lite | perl-SOAP-Lite from EPEL
|
net/p5-SOAP-Lite
|
DateTime::TimeZone: use version 0.34 or later
Versions of DateTime::TimeZone (a component of DateTime) below 0.34 suffer from a problem with displaying some time zones. Make sure you have version 0.34 or later.
Problems building Time::HiRes
Some users have reported problems building Time::HiRes through CPAN. If this is your experience, try downloading the Time::HiRes tarball from http://search.cpan.org/~jhi/Time-HiRes/ and building it manually (perl Makefile.PL && make && make test && make install
).
Problems building Apache::Request or Apache2::Request
Apache::Request is one component of the libapreq library. If you run into problems building it through CPAN, try downloading the libapreq tarball from http://httpd.apache.org/apreq/.
Apache 2.0.x users should use libapreq2.
mod_perl
WeBWorK uses mod_perl to interface with the Apache server. If compiling mod_perl from source, use the EVERYTHING=1
flag to enable all mod_perl features. Most vendors compile their mod_perl packages with this setting enabled.
Apache 1.3
- Source: http://perl.apache.org/download/
- Debian/Ubuntu:
libapache-mod-perl
- Red Hat/Fedora: build from source; see below.
- Gentoo:
mod_perl
Apache 2.0
- Source: http://perl.apache.org/download/
- Debian/Ubuntu:
libapache2-mod-perl
- Red Hat/Fedora: build from source
RHEL4/Fedora build notes
I had to use the flags below to get the compile to work correctly:
perl Makefile.PL EVERYTHING=1 DO_HTTPD=1 USE_APACI=1 APACHE_PREFIX=/usr/local/apache
-- Main.MarkHamrick
MySQL
MySQL 4.0.x or later is required. If you are going to be using the experimental Moodle Integration, MySQL 4.1.x or later is required.
- Source: http://dev.mysql.com/downloads/
- Debian/Ubuntu: 4.0.x:
mysql-server
; 4.1.x:mysql-server-4.1
- Red Hat EL/Fedora/CentOS:
mysql-sever
and depending on distro release, eithermysql-client
ormysql
- Gentoo:
mysql
- FreeBSD:
databases/mysql*-server
LaTeX
WeBWorK requires LaTeX for generating hardcopy output and displaying mathematics graphically. Any standard LaTeX distribution that provides the commands latex
and pdflatex
should work. We use TeTeX.
- Source: http://tug.org/tetex/
- Debian/Ubuntu:
tetex-bin
,tetex-extra
- Red Hat/Fedora:
tetex
,tetex-latex
- Gentoo:
tetex
- FreeBSD:
print/teTeX
Netpbm
WeBWorK requires Netpbm to convert images among the GIF, PNG, and EPS formats.
- Source: http://netpbm.sf.net/
- Debian/Ubuntu:
netpbm
- Red Hat/Fedora/CentOS:
netpbm-progs
- Gentoo:
netpbm
- FreeBSD:
graphics/netpbm
dvipng
WeBWorK uses dvipng to display mathematics graphically. It is only required if you wish to use the images
display mode. dvipng requires the preview.sty
file from the preview-latex package.
- Source: http://dvipng.sf.net/
- Debian:
dvipng
,preview-latex-style
- Red Hat/Fedora/CentOS:
tetex
,preview-latex-common
- Gentoo:
dvipng
- FreeBSD:
print/teTeX
WeBWorK is initially configured to work with dvipng 1.0 or greater, but can be reconfigured to work with dvipng 0.8 or 0.9. See webwork2/lib/WeBWorK/Constants.pm
for details.
TtH
WeBWorK uses TtH to display mathematics as formatted HTML. It is only required if you wish to use the formatted-text
display mode.
- Source: http://hutchinson.belmont.ma.us/tth/
- Debian:
tth
- Red Hat/Fedora/CentOS:
tth
from Nogin, or build from source - Gentoo:
tth
- FreeBSD:
textproc/tth
Installing the WeBWorK files
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 writable by other users:
# cd /opt/webwork/pg # chown -R root:root . # chmod -R u=rwX,go=rX .
Most WeBWorK directories and files should also be owned by root and not writable by other users:
# cd /opt/webwork/webwork2 # chown -R root:root . # chmod -R u=rwX,go=rX .
Certain data directories need to be writable by the web server. These are 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.
The simplest way to set this up assumes that all WeBWorK administrators have root access. In this case, directories that must be writable by the web server should be given the group of the web server. In the following examples, it is assumed that the web server's group is httpd
.
If you wish to perform administrative tasks without becoming root, you can either add the WeBWorK administrators to the web server's group, or create a new group called wwdata
, containing both the WeBWorK administrators and the web server.
If you chose not to create the wwdata
group, the WeBWorK data directories should have the group of the web server:
# cd /opt/webwork/webwork2 # chgrp -R httpd DATA ../courses htdocs/tmp logs tmp # chmod -R g+w DATA ../courses htdocs/tmp logs tmp # find DATA/ ../courses/ htdocs/tmp/ logs/ tmp/ -type d -a ! -name CVS -exec chmod g+s {} \;
If you chose to create the wwdata
group, the WeBWorK directories that must be writable by the web server should have that group:
# cd /opt/webwork/webwork2 # chgrp -R wwdata DATA ../courses htdocs/tmp logs tmp # chmod -R g+w DATA ../courses htdocs/tmp logs tmp # find DATA/ ../courses/ htdocs/tmp/ logs/ tmp/ -type d -a ! -name CVS -exec chmod g+s {} \;
CVS updates and permissions
In the instructions above, you set most WeBWorK and PG files to be owned and only writable by root. If you are planning to do in-place updates of the system with CVS, you may want to set those files to be owned by a regular user instead. That will let you avoid running CVS as root, which could be a security risk. One option is to create a user account that cannot be logged into directly and use it only for WeBWorK files.
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.
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:
- Test the
/webwork2
location by visitinghttp://yourserver.yourschool.edu/webwork2
. You should see the WeBWorK home page, with no courses listed. - Test the
/webwork2_files
location by visitinghttp://yourserver.yourschool.edu/webwork2_files
. You should see the "WeBWorK Placeholder Page". - You cannot test the
/webwork2_course_files
location until you have created a course.
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
.
Creating the admin course
WeBWorK includes web-based course management tools. Access to these tools is controlled by a special course named admin
. The instructors in this course are permittied to perform administrative functions. If the admin course exists, a Course Administration link will appear on the WeBWorK home page.
If you created a wwadmin
group, create the admin course as follows:
$ cd /opt/webwork/courses $ newgrp wwadmin $ umask 2 $ addcourse $ addcourse admin --db-layout=sql_single --users=adminClasslist.lst --professors=admin $ exit
If you did not create a wwadmin
group, create the admin course as follows:
$ sudo -u www-data addcourse admin --db-layout=sql_single --users=adminClasslist.lst --professors=admin
Replace www-data
with the user your webserver runs as.
See CourseAdministrationManual#Permissions_issues for more about getting the permission right when using the command-line tools.
If you get an error about WEBWORK_ROOT not being found in the environment (and it is set in your ~/.bashrc), try this instead:
$ sudo -u www-data env WEBWORK_ROOT=/opt/webwork/webwork2 addcourse admin --db-layout=sql_single --users=adminClasslist.lst --professors=admin
After you create the course, visit the WeBWorK home page on your server, usually located at http://yourserver.yourschool.edu/webwork2
. Click on the Course Administration link. You can also access the admin course directly, at http://yourserver.yourschool.edu/webwork2/admin
.
To log in, enter admin
for your username and admin
for your password. Once logged into the admin course, the first thing you should do is change the password for the admin account. You can do this by clicking the Password/Email link on the links menu. After you do this, you may add accounts for any additional people who should have administrative access using the Class List Editor link.
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.