Installation Manual for 2.2

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.

Satisfying system requirements

WeBWorK requires several software packages to run.

OS vendor package names are supplied. (Feel free to add the package names for additional vendors. Thanks to Mark Hamrick)

Perl

WeBWorK requires Perl 5.6 or greater.

Package names:	Debian:	=perl=
	RHEL4, Fedora:	Part of default install, `perl`

Apache

WeBWorK requires Apache 1.3. Efforts are underway to make it compatible with Apache 2. WeBWorK requires that the mod_alias module be available. Most vendors compile their Apache packages with the necessary features enabled.

Package names:	Debian:	`apache`
	RHEL4, Fedora:	Compile from source

mod_perl

WeBWorK is a mod_perl application and requires mod_perl 1.x. 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.

Package names:	Debian:	`libapache-mod-perl`
	RHEL4, Fedora:	Compile from source. 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=`

MySQL

In WeBWorK 2.2, only MySQL database are supported. The deprecated GDBM database has been removed in this version. WeBWorK 2.2 is primarily tested with MySQL 4.0. It also reported to work with MySQL 4.1 as well as recent versions of MySQL 3.

Package names:	Debian Fedora, RHEL:	`mysql-server`, `mysql-client`

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.

Package names:	Debian:	`tetex-bin`, `tetex-extra`
	RHEL4, Fedora:	`tetex`, `tetex-latex`

Netpbm

WeBWorK requires Netpbm to convert images among the GIF, PNG, and EPS formats.

Package names:	Debian:	`netpbm`
	RHEL4, Fedora:	Compile from source.

dvipng

WeBWorK uses dvipng to display mathematics graphically. It is only required if you wish to use the images display mode. 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. dvipng requires the preview.sty file from the preview-latex package.

Package names:	Debian:	`dvipng`, `preview-latex-style`
	Fedora:	`preview-latex-common-0.9.1-1.fedora.noarch.rpm`

TtH

WeBWorK uses TtH to display mathematics as formatted HTML. It is only required if you wish to use the formatted-text display mode.

Package names:	Debian:	`tth` (available in Debian testing only)
	RHEL4, Fedora:	Compile from source.

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 installed on your system, issue the following command, replacing Module with the name of the module: perl -MModule -e 'print "installed!\n"'

To install a module from CPAN, issue the following command as root, replacing Module with the name of the module: # perl -MCPAN -e "install Module"

module	vendor package names
Apache::Request	Debian: `libapache-request-perl`
Data::UUID	Debian: build from source
String::ShellQuote	Debian: build from source
DateTime	Debian: `libdatetime-perl`
Date::Format	Debian: `libtimedate-perl`
Date::Parse	Debian: `libtimedate-perl`
GD	Debian: `libgd-gd2-perl`
Mail::Sender	Debian: `libmail-sender-perl`
Time::HiRes (included in Perl 5.8 and higher)	Debian: included in `perl` package
XML::Parser	Debian: `libxml-parser-perl`
XML::Parser::EasyTree	Debian: build from source
XML::Writer	Debian: `libxml-writer-perl`
DBI	Debian: `libdbi-perl`
DBD::mysql	Debian: `libdbd-mysql-perl`

Some users have reported problem installing Time::HiRes through CPAN. If this is your experience, try downloading the Time::HiRes tarball from http://search.cpan.org/~jhi/Time-HiRes/ and installing it manually (perl Makefile.PL && make && make test && make install).

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. (more notes for DateTimeModule )

---

Installing a new WeBWorK system

WeBWorK can be installed from a tarball or from CVS. Tarballs are made for each release. They contain the necessary CVS data to update from CVS at a later date. Choose a tarball if you want to only run released versions or do not want to bother setting up CVS.

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.2.tar.bz2 $ tar -xjf pg-2.2.tar.bz2

Then, become root and move the directories to the your installation directory. I prefer /opt: # cp -r webwork-2.2 /opt/webwork2 # cp -r pg-2.2 /opt/pg

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

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.

  Released version: By specifying the rel-2-2-0 tag, you get the same version of the code that you would by downloading the WeBWorK 2.2.0 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-2-dev tag, you can stay up to date with the latest bug fixes against the released version of WeBWorK 2. Few, if any, new features are introduced on a patch branch. We recommend that you chose this option.
  Latest development code: If you do not specify a release tag, you will get the latest development code. Since this code is a work in progress, it is sometimes unstable or broken.

No matter what tag you chose, you can change later.

Before you can install from CVS, follow the instructions in the WeBWorKCVSReadOnly topic to configure anonymous read-only access to our CVS repository. After installing the SSH helper script and configuring the cvs alias,

Use the following commands to check out working 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-2-0 webwork2 pg

Released version with patches: cvs -d :pserver:anoncvs@cvs.webwork.rochester.edu:/webwork/cvs/system checkout -r rel-2-2-dev webwork2 pg

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

After checkout finishes, become root and move the directories to the your installation directory. I prefer /opt: # cp -r webwork2 /opt/webwork2 # cp -r pg /opt/pg

Setting permissions

The PG installation directory and files should be owned by root and not writeable by other users: # cd /opt/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/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 writeable 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 www-data.

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: # chgrp -R www-data 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 {} \;

If you chose to create the wwdata group, the WeBWorK directories that must be writable by the web server should have that group: # 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 {} \;

---

Upgrading an existing WeBWorK installation

If you already have a WeBWorK system installed on your server, you can upgrade it. This section will cover upgrading your installation to WeBWorK version 2.2.

Before you upgrade

WeBWorK 2.2 removes the gdbm and sql database layouts. If you have courses that use either of these layouts, and you want to continue to use them, you must convert them to sql_single before updating to WeBWorK 2.2.

To convert an sql course to sql_single, follow the instructions Converting an existing course from 'sql' to 'sql_single' in the CourseAdministrationManual.

GDBM courses cannot be converted automatically. However, you can use the database export/import functionality to create a new course with the same data as the old course:

Export the GDBM course's database
Create a new course, specifying the existing GDBM course for the option "To copy problem templates from an existing course, select the course below".
Import the GDBM course's database into the new course

Note that the above procedure only copies the course database and the templates directory -- other files in the course directory must be copied manually.

Upgrading using 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 GZip or BZip2 archives.

After downloading the tarballs, untar them somewhere (like your home directory): $ tar -xjf webwork-2.2.tar.bz2 $ tar -xjf pg-2.2.tar.bz2

Then, copy the WeBWorK configuration files and courses directory from your current installation. If your courses are stored outside the webwork2 tree, there is no need to copy them. $ cd webwork-2.2 $ cp /opt/webwork2/conf/{global,database}.conf conf $ cp -r /opt/webwork2/courses .

Now you need to compare your configuration files with the new distribution versions. This can be done with the diff command. Make any updates necessary, as per Making changes fo the new release, below: $ cd conf $ diff database.conf database.conf.dist $ diff global.conf global.conf.dist

Then, become root and replace your current installation: # mv /opt/webwork2 /opt/webwork2.OLD # cp -r webwork-2.2 /opt/webwork2 # mv /opt/pg /opt/pg.OLD # cp -r pg-2.2 /opt/pg

Finally, reset file permissions, using the instructions for Setting permissions above.

Upgrading using CVS

With a few simple commands, you can update your existing WeBWorK system via CVS.

To update your system to the latest released version, change to your webwork2 installation directory and use the cvs command: cvs update -d -r rel-2-2-0

Now you need to compare your configuration files with the new distribution versions. This can be done with the diff command. Make any updates necessary, as per Making changes fo the new release, below: $ cd conf $ diff database.conf database.conf.dist $ diff global.conf global.conf.dist

Making changes for the new release

Because of changes in WeBWorK's configuration between releases, it may be necessary for you to make changes to your configuration files or existing courses after upgrading. The instructions below cover the changes since the latest version in the 2.1.x series. If you have skipped releases, go back and read the release notes for the releases you have skipped. Follow any upgrade directions sequentially, before reading the section below.

Changes to the database

Several fields have been added to the database format to support gateway testing. The utility wwdb_addgw will add these fields to existing courses: $ cd bin $ ./wwdb_addgw

wwdb_addgw will prompt you for:

A MySQL account that has ALTER privileges (defaults to root, webworkWrite should be sufficient).
The password for that MySQL account.
The database type (select sql_single, which is the default).

It will then show you a list of courses that it plans to update. If you want to exclude a course from this list, type d#, where =#= is the number of the course in the list. When you are ready, hit Enter to update the remaining courses.

Changes to global.conf

A new item $externalPrograms{tar} has been added. It should be set to the path to tar on your system.
Paths to several Netpbm utilities have been added. Ensure that these are set to the paths to the corresponding utilities on your system.
- $externalPrograms{giftopnm}
- $externalPrograms{ppmtopgm}
- $externalPrograms{pnmtops}
- $externalPrograms{pnmtopng}
- $externalPrograms{pngtopnm}
In addition, the scripts gif2eps, png2eps, and gif2png in the WeBWorK bin directory have been replaced by the items $externalPrograms{gif2eps}, $externalPrograms{png2eps}, and $externalPrograms{gif2png}, respectively. The values should not need to be modified.
The behavior of $mail{feedbackRecipients} has changed. Previously, if this item was not defined (i.e. commented out or set to the value undef), feedback emails would be sent to all instructors and TAs. Now, it behaves as described in global.conf.
The subject line for feedback emails is now customizable via the $mail{feedbackSubjectFormat} item.
There is a new item $webworkDirs{templates} for the location of the HTML theme templates. It is set to the templates subdirectory of the WeBWorK conf directory.
The File Manager module will now follow symbolic links if the targets are listed in $webworkDirs{valid_symlinks}. This is useful for things like maintaining a shared directory for set definition files or classlists.
The URL to jsMath, $webworkURLs{jsMath}, has changed.
Since GDBM is no longer supported, the $courseDirs{auth_DATA} item has been removed.
The new item $courseDirs{tmpEditFileDir} stores the path to a directory used when editing PG files.
The new item $courseFiles{simpleConfig} stores the path to an additional course configuration file used by the web-based Course Configuration module.
The only valid value for $dbLayoutName is now "sql_single" (unless you add a custom database layout).
The new item $problemLibrary{version} controls which version of the database-based problem library will be used.
The new item $courseFiles{logs}{login_log}, if set, will cause WeBWorK to log logins (successful and unsuccessful) to the file given.
The new item $courseFiles{logs}{activity_log}, if set, will cause WeBWorK to log almost every click. When turned on, this log can get quite large.
The status system has been changed. Instead of $siteDefaults{status}, statuses are controlled by the $default_status and %statuses items. These items are explained in global.conf.
The %templates hash has been replaced with the $defaultTheme and $defaultThemeTemplate items.
The permissions system now maps numeric permission levels to names like "guest", "student", etc. using the %userRoles hash. This allows the classlist editor to report meaningful names rather than numbers. The %permissionLevels hash will need to be modified to reflect this.
A new item $gatewayGracePeriod has been added to accomodate gateway testing.
The user and passwd settings of the dvipng_depth_db item has been changed to refer to the sql_single username and password settings rather than the sql settings (since the sql database layout no longer exists).
There are now Parser-based implementations of the num_cmp and fun_cmp answer evaluators. The new item $pg{specialPGEnvironmentVars}{useOldAnswerMacros} can be set to =1= to use the original implementations.
Two configuration items, $pg{specialPGEnvironmentVars}{problemPreamble} and $pg{specialPGEnvironmentVars}{problemPostamble} have been added to allow "wrapping" of PG output in HTML or TeX code (depending on the display mode).
The item [qw(Parser::Legacy)] has been added to the ${pg}{modules} list.

Changes to database.conf

The $dbLayouts{gdbm} and $dbLayouts{sql} items have been removed, because these database layouts are no longer supported.

Changes to webwork.apache-config

Web service related items are now commented out by default.

Changes to jsMath

The latest verion of jsMath includes a new fallback support method for when the student does not have the TeX fonts installed on his or her computer. It uses images of the individual TeX characters in place of the characters themselves, but this requires a large number of images in a variety of sizes. These fonts are distributed in the tarball which must be unpacked before they are available, and jsMath fallback mode will not work properly without them. See jsMath Settings below for details.

After making changes

After the update is complete, restart your Apache server and test your installation to make sure everything works.

---

Tracking updates between releases

As we find bugs, we fix them and add them to the rel-2-2-dev branch of CVS. Periodically, we create patchlevel releases from that branch, such as rel-2-2-1, that encompas the changes made since the last release. Each patchlevel release is available as a tarball and from CVS. The -dev branch is only available from CVS.

To update your system to include the latest patches, change to your webwork2 installation directory and use the cvs command: cd /opt/webwork2 cvs update -d -r rel-2-2-dev

The WeBWorK project maintains a mailing list to which every update to our CVS repository is posted. You might find it helpful to subscribe to this list to see when bugs have been fixed. See http://lists.sourceforge.net/lists/listinfo/openwebwork-cvs for more information.

---

Configuring the shell

To make working with WeBWorK easier, there are a couple of changes you can make to your shell environment.

Add the WeBWorK bin directory to your path. This will allow you to run WeBWorK command-line utilities without typing the full path to the utility. If you installed WeBWorK in the default location of /opt/webwork2, add the directory /opt/webwork2/bin to your path.

if your shell is	put this line	in this file
`bash`	`export PATH=$PATH:/opt/webwork2/bin`	`~/.bashrc`
`tcsh`	`setenv PATH $PATH:/opt/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/webwork2`	`~/.bashrc`
`tcsh`	`setenv WEBWORK_ROOT /opt/webwork2`	`~/.cshrc`

---

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.

---

Configuring WeBWorK

Making copies of the distribution configuration files

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

Global configuration

Most WW configuration is done in the file /opt/webwork2/conf/global.conf. This file provides system-wide configuration settings, and defaults for course settings. Any setting in this file can be overridden in the course.conf file for a particular course.

There are several options that must be set for 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/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.

dvipng depths database

When using the images display mode, dvipng can generate information about the location of the text baseline in the generated image. Using this information will make the equation images "fit in" with surrounding text better.

To enable, create a DvipngDepths MySQL database as follows: CREATE DATABASE DvipngDepths; USE DvipngDepths; CREATE TABLE depths (md5 CHAR(33) NOT NULL, depth SMALLINT, PRIMARY KEY (md5)); GRANT ALL ON DvipngDepths.* TO webworkWrite;

Then, set the option dvipng_align in the $pg{displayModeOptions}{images} to mysql.

Database configuration

Important: In earlier version of WeBWorK 2, several database layouts were supported. In WeBWorK 2.2, the only supported database layout is sql_single. If you are upgrading, you should have converted existing courses which use the gdbm or sql database layouts before you upgraded. (See Before you upgrade, above.)

The sql_single database layout uses a MySQL database server to store the tables of the WeBWorK database. The SQL driver uses two SQL accounts, a read only and a read-write account. The read-only account must have SELECT access, and the read-write account needs SELECT, INSERT, UPDATE, and DELETE access. When courses are created, the required permissions are assigned to the read-only and read-write SQL accounts.

The names and passwords of these accounts are given as parameters to each table in the layout.

param	description
`usernameRO`	the name of the read-only account
`usernameRW`	the name of the read-write account
`passwordRO`	the password for the read-only account
`passwordRW`	the password for the read-write account

Don't confuse the accounts above with the accounts of the users of a course. These are accounts on the database server itself, which allow WeBWorK to talk to the database server.

By default, the name of the read-only account is "webworkRead", and the name of the read-write account is "webworkWrite". There are no passwords by default. We recommend that you set passwords for these accounts in database.conf. However, we do not recommended that you use only passwords to secure database access. Most RDBMSs allow IP-based authorization as well. As the system administrator, it is your responsibility to secure database access.

In database.conf, usernameRO, usernameRW, passwordRO, and passwordRW, and debug are set in the %sqlParams hash: my %sqlParams = ( usernameRO => "webworkRead", passwordRO => "", usernameRW => "webworkWrite", passwordRW => "", debug => 0, );

Other parameters that can be given are as follows:

param	description
`tableOverride`	an alternate name to use when referrring to the table (used when a table name is a resereved word)
`fieldOverride`	a hash mapping WeBWorK field names to alternate names to use when referring to those fields (used when one or more field names are reserved words)

These overrides should be set for a specific table, not for all tables in the %sqlParams hash.

In addition, the variable $sqlSingleDBISource is used to populate the source attribute for each table. It is a DBI source speicifications and controls the type of database that is used, the name of the database, and the how to connect. By default, the MySQL driver is used and the database is named webwork. For more information about DBI source speicifications, refer to: the Perl DBI documentation.

Since sql_single uses a single database for all courses using the layout, it does not create databases when courses are created. Instead, you must create a single database. Create the database using the your database server's command console. Then grant the users listed for usernameRO and usernameRW the following permissions for that database.

username	permissions
`$sqlParams{usernameRO}` (usually `webworkRead`)	`SELECT`
`$sqlParams{usernameRW}` (usually `webworkWrite`)	`SELECT`, `INSERT`, `UPDATE`, `DELETE`, `CREATE`, `ALTER`, `DROP`

For example, under MySQL: $ mysql -u root -p mysql Password: '''***''' > CREATE DATABASE webwork; > GRANT SELECT ON webwork.* TO webworkRead@localhost IDENTIFIED BY 'passwordRO'; > GRANT SELECT, INSERT, UPDATE, DELETE, CREATE, ALTER, DROP ON webwork.* TO webworkWrite@localhost IDENTIFIED BY 'passwordRW'; > exit Bye $

Replace passwordRO and passwordRW with the passwords you have set in the %sqlParams hash.

Constants.pm

Some configuration settings are stored in the file /opt/webwork2/lib/WeBWorK/Constants.pm.

ImageGenerator settings

The $WeBWorK::PG::ImageGenerator::DvipngArgs variable specifies the arguments to use when calling dvipng. dvipng version 1.0 and later require a different set of arguments than versions 0.9 and earlier:

version	arguments
< 1.0	`-x4000.5 -bgTransparent -Q6 -mode toshiba -D180`
>= 1.0	`-bgTransparent -D120 -q -depth`

jsMath settings

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

This will unpack the archive. Since there are 20,000 tiny files, it can take a long time, so the v= option is used to show you the names as they are unpacked so that you know the command is actually doing something. Once the images are unpacked, jsMath's image mode fallback (the default fallback method) will work properly, and most students will have results as good as they would with the TeX fonts installed. If you do not wish to install the jsMath image fonts (to save space, for example), you should change the value of =noImageFonts in the $pg{displayModeOptions}{jsMath} in global.conf to 1. This will prevent jsMath from using the image fallback methods.

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

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

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

---

Configuring Apache

WeBWorK requires mod_perl to run. To test your mod_perl installation, enable the following stanza in your Apache config file (usually httpd.conf or apache.conf): <Location /server-info> SetHandler server-info Order deny,allow Deny from all Allow from .yourschool.edu </Location>

Then restart Apache: apachectl graceful

Visit http://yourserver.yourschool.edu/server-info. You should see an entry in the list of active modules for mod_perl.

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/webwok2/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/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 <ocation> and <Directory> stanzas, to permit access: Order allow,deny Allow from all

After configuring webwork.apache-config, append the following line to your Apache configuration file: Include /opt/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 visiting http://yourserver.yourschool.edu/webwork2. You should see the WeBWorK home page, with no courses listed.
Test the /webwork2_files location by visiting http://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.

---

Where to go from here

Read the CourseAdministrationManual for information about creating courses.

Consult the WeBWorKDocs topic for other WeBWorK documentation.

---

-- Main.SamHathaway - 07 Jul 2004
-- Main.SamHathaway - 15 Jul 2004
-- Main.SamHathaway - 21 Jul 2004
-- Main.SamHathaway - 24 Aug 2004
-- Main.SamHathaway - 25 Aug 2004
-- Main.SamHathaway - 11 Sep 2004
-- Main.SamHathaway - 13 Sep 2004
-- Main.SamHathaway - 17 Sep 2004
-- Main.MichaelGage - 12 Feb 2005
-- Main.SamHathaway - 11 Jul 2005
-- Main.SamHathaway - 26 Aug 2005
-- Main.DavideCervone - 03 Sep 2005 (added jsMath details)
-- Main.SamHathaway - 06 Jan 2006 (updates for 2.2)
-- Main.SamHathaway - 13 Jan 2006 (current release is rel-2-2-pre1)
-- Main.SamHathaway - 13 Feb 2006 (current release is rel-2-2-0)
-- Main.SamHathaway - 18 Apr 2006 (added wwdb_addgw instructions)