Installation Manual for 2.0

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

Perl

WeBWorK requires Perl 5.6 or greater. To use courses with GDBM databases (such as those created by WeBWorK 1), Perl must be compiled with support for libgdbm. Most vendors compile their Perl packages with this support enabled.

Package names: Debian: 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

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

SQL server

While one can continue to use hash-style databases (usually GDBM) to store course data (as was done in WeBWorK 1), we recommend that you use an SQL server to store course data for new courses you create under WeBWorK 2. Using SQL will make your courses faster, especially under heavy loads. A single installation of WeBWorK 2 can support courses using both hash-style databases and SQL databases. Courses using SQL are not compatible with WeBWorK 1. However, course databases can be exported to an XML format if needed.

WeBWorK 2 is primarily tested with MySQL 3. It also works with MySQL 4. With small code changes, it can be made to work with other SQL databases for which there is a Perl DBD:: module. (For example, DBD::sqlite or DBD::Oracle.)

Package names: Debian: 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

Netpbm

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

Package names: Debian: netpbm

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

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

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	condition	vendor package names
Apache::Request	required	Debian: libapache-request-perl
Data::UUID	required	Debian: not available
Date::Format, Date::Parse	required	Debian: libtimedate-perl
GD	required	Debian: libgd-gd2-perl
Mail::Sender	required	Debian: libmail-sender-perl
Time::HiRes	required	Debian: libtime-hires-perl
XML::Parser	required	Debian: libxml-parser-perl
XML::Parser::EasyTree	required	Debian: not available
XML::Writer	required	Debian: libxml-writer-perl
DBI	required if using SQL databases	Debian: libdbi-perl
DBD::mysql	required if using MySQL databases	Debian: libdbd-mysql-perl

Module notes:

• If you run into problems installing Time::HiRes through CPAN, it may help to install it manually (make && make test && make install).

---

Installing WeBWorK

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.0.tar.bz2 $ tar -xjf pg-2.0.tar.bz2

Then, become root and move the directories to the your installation directory. I prefer /opt: # cp -r webwork-2.0 /opt/webwork2 # cp -r pg-2.0 /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-0 tag, you get the same version of the code that you would by downloading a 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-0-patches 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.
  Latest development code: By checking out the latest code (via the HEAD tag), you 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 wwcvs alias, use the following commands to check out a working copy of the webwork2 and pg modules:

Released version: wwcvs -d :ext:anoncvs@cvs.webwork.rochester.edu:/webwork/cvs/system checkout -r rel-2-0 webwork2 pg

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

Latest development code: wwcvs -d :ext:anoncvs@cvs.webwork.rochester.edu:/webwork/cvs/system checkout -r HEAD 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

Most WeBWorK directories and files should 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.

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 such as removing temporary files, creating and editing courses from the command line, managing logs, and so on, 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 conf courses htdocs logs tmp # find DATA/ conf/ 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 conf courses htdocs logs tmp # find DATA/ conf/ courses/ htdocs/ logs/ tmp/ -type d -a ! -name CVS -exec chmod g+s {} \;

---

Upgrading WeBWorK

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

Upgrading using CVS

With a few simple commands, you can track changes on the -patches branch. This allows you to get the latest patches as quickly as possible.

If you did not install from CVS, follow the instructions in the WeBWorKCVSReadOnly topic to download the CVS helper script and set up the wwcvs alias. To update your system to include the latest patches, change to your webwork2 installation directory and use the wwcvs command: cd /opt/webwork2 wwcvs update

If you wish to stick to patchlevel releases, issue the following command instead, replacing release with the name of a patchlevel release (i.e. rel-2-0, rel-2-0-3). wwcvs update -r release

Upgrading using a tarball

Each patchlevel release is available in tarball form on our SourceForge project page: http://sourceforge.net/project/showfiles.php?group_id=93112

Start by downloading the appropriate tarball. Change to the directory containing the webwork2 directory and untar the tarball: cd /opt tar -xjf webwork-2.0.1.tar.bz2

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

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. For releases (patchlevel, minor, or major), read the release notes for the release to which you're upgrading. If you have skipped releases, go back and read the release notes for the releases you have skipped. Follow any upgrade directions sequentially, by release.

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

---

Configuring the shell

To make working with WeBWorK easier, there are several 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/webwok2/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.

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.

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

Database configuration

The database configuration is controlled by the dbLayout hash. Various versions of this hash are defined in the configuration file database.conf, which is incorporated into global.conf using the include function.

Each database layout is defined as a key in the %dbLayouts hash. The layouts currently defined are as follows:

layout	description
$dbLayouts{sql}	Defines dbLayout to use a database on an SQL server. Suitable for courses that will only be used under WW2.
$dbLayouts{gdbm}	Defines dbLayout to use GDBM databases stored in the DATA subdirectory of each course's directory. Suitable for courses that were created under WW1, or course that are to be shared between WW1 and WW2.

To select a database layout, use the following syntax, replacing layoutName with either gdbm or sql: $dbLayoutName = "layoutName"; *dbLayout = $dbLayouts{$dbLayoutName};

Which database layout you chose for the global default (i.e. set in global.conf) depends on what database backend your courses will usually use. Courses with a different database layout will require a different layout to be selected in that course's course.conf file.

If you have WW 1 courses that you'd like to use under WW 2, set the database layout to "gdbm". This way, the WW 2 will be able to read the WW 1 course databases even though those courses do not have a course.conf file. Even with this setup, new courses should still use "sql", unless you need them to be usable under WW 1.

Please note: support for GDBM databases are provided only for backwards compatability with courses used under WeBWorK 1 and will be dropped in a future version of WeBWorK 2 (as will all non-SQL database support).

Options specific to a particular database layout are described in the file database.conf. It is recommended that you peruse that file and ensure that these values are set correctly for your site. In particular, it is important to set database access passwords for the SQL database layout.

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

Image conversion utilities

WeBWorK uses several support utilities -- gif2eps, gif2png, and png2eps -- for converting images. These scripts can be found in the directory /opt/webwork2/bin.

These scripts make use of several of the Netpbm tools, and therefore need to be told where to find them. Each script defines a variable called NETPBM, which is initially set to /usr/local/bin. If your netpbm tools were not installed to /usr/local/bin, change the value of this variable to reflect their actual location.

To determine where netpbm is installed, search for the program giftopnm, one of the programs that makes up the netpbm package. The directory that contains that file (for example /usr/bin or /usr/local/netpbm/bin) is the location you're looking for.

---

Configuring Apache

WeBWorK is nothing without mod_perl. 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, add the following to your Apache configuration file: Include /opt/webwork2/conf/webwork.apache-config

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.

---

Creating the admin course

Administrative functions or WeBWorK are implemented via a special course named admin. The users of this course are permitted to perform administrative functions.

Use the command-line addcourse utility to create the admin course. $ cd /opt/webwork2 $ bin/addcourse --db-layout=sql --sql-user=root --sql-pass=secret --sql-db=webwork_admin \ --sql-wwhost=localhost --users=courses/adminClasslist.lst --professors=admin admin

This command creates a course named admin, storing course data in an sql database named webwork_admin. --sql-user and --sql-pass specify the username and password of a user of the SQL database server that has permission to create databases.

Users are imported from the file courses/adminClasslist.lst, and the user admin (the only user listed in adminClasslist.lst) is given professor privileges.

Before proceeding to the next step, make sure that the permissions on the directory courses/admin/ and files and subdirectories within it allow access by the web server.

To test, visit http://yourserver.yourschool.edu/webwork2/admin/. You should be able to log in with the username admin and the password admin. Change that password as soon as possible using the User Options link.

Once you've created the admin course, you can create additional courses over the web.

---

Creating a test course

To create a test course, visit http://yourserver.yourschool.edu/webwork2/admin/. Select Add Course and fill in the information required.

---

-- Main.SamHathaway - 07 Jul 2004
-- Main.SamHathaway - 15 Jul 2004
-- Main.SamHathaway - 21 Jul 2004
-- Main.SamHathaway - 24 Aug 2004