WeBWorK dev-1-7-01 Linux install | topic started 8/14/2001; 4:59:24 PM last post 8/14/2001; 4:59:24 PM |
Sam Hathaway - WeBWorK dev-1-7-01 Linux install 8/14/2001; 4:59:24 PM (reads: 839, responses: 0) |
Installing WeBWorK on a Linux SystemSamuel Hathaway, <sh002i@math.rochester.edu>; This document will guide you through the installation of WeBWorK and its support packages. I assume the reader has prior experience with UNIX system administration tasks such as compiling software, configuring the Apache server, etc. Most steps in the installation process can be done as a normal user. However, some steps must be done as the root user. While attempts have been made to minimize the number of commands that must be executed as root, it is still important to be cautious whenever using the root account. Within this document, commands given by root will be prefixed with "#" while commands given by a normal user will be prefixed with ">". Note that throughout this document, all references to a "normal user" refer to the same normal user. Step 1: Installing PerlOn most Linux distributions, the distribution version of perl is adequate for use with WeBWorK. In particular, perl must be compiled with GDBM database support. Whether this is so can be determined in one of two ways: For static linkage, check the > perl -V | grep libs= If GDBM is not present in either of these outputs, perl needs to be
recompiled with GDBM support. The perl compilation process will
automatically compile GDBM support if GDBM the libraray is detected.
Most Linux distributions come with the GDBM library. It is called Please note that if you recompile perl, you may have to be careful
about maintaining two copies of perl on your system. In particular,
make sure that when you type Step 2: Installing additional packagesAs root, use CPAN to install additional perl modules needed for WeBWorK. If this is the first time you're run CPAN, you will be required to configure it. # perl -MCPAN -e shell CPAN may prompt you for configuration settings for the modules you are installing. Next, you will need to install several support programs used by WeBWorK. Most distributions include packaged versions of these programs, but they are not always installed by default. Consult the documentation for your distribution to find out if you can use a prepackaged version. If you wish, you can also install from source:
LaTeX2HTMLLaTeX2HTML has some dependancies of its own. Consult the LaTeX2HTML Requirements Page for more information. Only LaTeX2HTML version 96.1 and 98.1p1 have undergone extensive testing with WeBWorK. WeBWorK ships with latex2html.init files for each if these versions. However, the init file for version 98.1p1 appears to work with later versions. LaTeX2HTML may be broken with respect to the WeBWorK system when
installed. To fix it, make sure the following configuration variables
are set as follows in the LaTeX2HTML configuration file, which may be
called $PK_GENERATION = 1 One of LaTeX2HTML dependancies is netpbm, which does not function properly in versions lower than 9.11. Either upgrade to version 9.11 or later, or apply the patches detailed at: http://webhost.math.rochester.edu/webworkdocs/discuss/msgReader$390 Step 3: Configuring ApacheNote: Since the locations of apache's document root and cgi-bin directories are distribution dependant, I will use Your apache configuration may need to be tweaked to allow WeBWorK to
function properly. First, you must make sure that apache runs as a real
system user and in a real system group, rather than as # useradd webwork You'll also want to add yourself to the webserver's group. As root: # usermod -G webwork,<othergroups> <username> Note: The Then, in the apache configuration file User nobody Change them so that they list User webwork There are two ways that the webserver can be given access to WeBWorK files. The first is to add an explicit In either case, your document root must have <Directory $DOCUMENT_ROOT> The important line is <Directory $CGI_BIN> If you chose to use a ScriptAlias /cgi-bin/webwork/system/ "/usr/local/webwork/system/cgi/" Make sure that these lines go before any existing Step 4: Installing the WeBWorK packageWeBWorK can be downloaded from following URL: http://webhost.math.rochester.edu/downloadwebwork/ If you haven't already, you need to register to be able to download files. The WeBWorK archives are named in the following form: webwork_VERSION_SUBVERSION-MONTH-DAY.tar.gz The As a normal user, download the latest versions of the webwork archive. Untar the WeBWorK archive using: > tar -xzf webwork_VERSION_SUBVERSION-MONTH-DAY.tar.gz This results in the creation of several readme files and the
webwork.tar archive, which contains the actual webwork system. Next we
must copy the # mv webwork /usr/local The WeBWorK files are now in their initial location. Next, a user
group must be created for users who are allowed to modify all WeBWorK
files. It is recommended that this group be named # groupadd wwadmin You can add any number of users with the second command, replacing
We'll make a webwork directory in apache's document root to contain a symlink to each course. We'll also give you ownership of this directory so you can add courses later without becoming root. As root, type the following: # mkdir $DOCUMENT_ROOT/webwork If you chose not to add a # mkdir $CGI_BIN/webwork We need to allow apache access to WeBWorK's html directory. As root, type: # ln -s /usr/local/webwork/system_html $DOCUMENT_ROOT/webwork_system_html Again, if you didn't add a > ln -s /usr/local/webwork/system/cgi $CGI_BIN/webwork/system The next step uses your normal user account, and requires membership
in the wwadmin group. Thus, you'll need to log out of this account and
then log back in. Next, we'll set the group of the entire WeBWorK
system to > chgrp -R wwadmin /usr/local/webwork/ These permissions are very lax, but that will be fixed when we run the setup script. As a normal user: > cd /usr/local/webwork/system This script will ask you several questions about the environment in which WeBWorK will be running. Read the information given with each choice carefully. Recommended choices are given in brackets, and can be accepted by pressing enter rather than typing a response. In order to use logging, you need to give the web server write access to the # chgrp -R webwork /usr/local/webwork/system/logs WeBWorK uses TTH, a C program which typesets TeX as HTML, using tables and other markup. TTH cannot be distributed with WeBWorK because of licencing issues. It can be obtained from the following URL: http://hutchinson.belmont.ma.us/tth/ As a normal user, download TTH to your home directory. Then untar, build, and install it with the following commands: > tar -xzf tth_C.tgz Then, as root, install it. # cp tth /usr/local/bin/ There are some user-definable settings that you should customize in the file Global.pm. This file is located at: ################################
Okay, now you've finished installing WeBWorK. However, there is one nuance which needs to be considered before proceeding. Step 5: Installing the problem set template filesBefore WeBWorK can be functional, problem set template files must be present. Download the templates archive from the WeBWorK web site, as you did with the WeBWorK archive. templates_VERSION_SUBVERSION-MONTH-DAY.tar.gz Move the templates archive to the WeBWorK directory and untar it. > mv templates_VERSION_SUBVERSION-MONTH-DAY.tar.gz /usr/local/webwork The problem set templates are not accessed directly from this location. They are instead copied into each course which is created. This allows professors to modify their local copies without disturbing other courses. Step 6: Creating a courseTo test your installation of WeBWorK, you must now create a course.
The template you will use to create this course is located in Each course has a UNIX user group associated with it. The group
should contain any users who should be able to view or edit the course
files directly (such as the professor and any teaching assistants), and
the system user under which the web server runs, As root, create a group for demoCourse and add yourself and the web server to it. Since we're adding the web server to a new group, we have to restart it: # groupadd DEMOCOURSE Now, log out of your normal user account and log back in so that your group membership will be recognized. Next, you will need to make a copy of > cd /usr/local/webwork/courses Repeat the last two commands for any other sets you wish to import into the demo course. A popular option is to import all of the sets. To do this, type: > cp -R /usr/local/webwork/templates/set* . WeBWorK comes with a script which completes the setup of a new course. We'll run it now, as a normal user: > cd /usr/local/webwork/courses/demoCourse This script will ask you several questions about the environment in which the course will be used. Read the information given with each choice carefully. Recommended choices are as follows: Q: Do you wish to setup a "working" or a "demo" version? (w or d) To let the WeBWorK system know that it has a new course, add a symlink to demoCourse to the system/courses directory. If you do not do this, the WeBWorK system will not be able to access the course this is a good way to "turn off" a course. > ln -s /usr/local/webwork/courses/demoCourse /usr/local/webwork/system/courses/ Each course has a "visible" interface in the webwork directory on
the web server's document root. This allows the course home page to be
accessed via > ln -s /usr/local/webwork/courses/demoCourse/html $DOCUMENT_ROOT/webwork/demoCourse Now, we're going to run some scripts to finish setting up the course. Now would be a good time to add the scripts directory to your search path, so that you don't have to type the full path of the command each time. If you are using bash, add this line to the bottom of the .bash_profile file in your home directory: PATH = "/usr/local/webwork/system/scripts:${PATH}" Log out and log back in again to add the new path. Now we'll run these scripts. As a normal user: > cd /usr/local/webwork/courses/demoCourse There. You've finished the demoCourse setup. The process for setting
up additional courses is identical to this. To verify that you've set
everything up properly, view the following URL in your browser: You should see your newly-generated course index page. If this works, click the Login button and enter the following information: login: professor Click Enter Professor's Page. You should now be logged in as the professor. Even though this is only the demo course, it's a good idea to change your password to prevent unauthorized access. While we're here, we can test to make sure that all of the problem rendering methods work. First, click Enter Build Problem Set Page. Then, select one or more problem sets from the list and click Build Problem Set(s). WeBWorK will report that the problem sets have been built. At the bottom of the resulting page, click Problem Sets. Now that the sets have been built, you can test various methods of displaying them. Select a set, select PDF form and click Get_hard_copy. After a moment, WeBWorK will send you a PDF file. Acrobat may open automatically, or you may have to wrestle with your browser a bit to see it. Next, we can check onscreen display. Select a problem set and click Do_problem_set. View several problems from the set on all three display modes: text, raw TeX source code, formatted-text, TTH output, and typeset, LaTeX2HTML output. Typeset mode takes quite some time on the first view of any problem as it has to generate images for the equations. However, subsequent views take advantage of cached temp files. Step 7: Separating Static and Variable WeBWorK dataRight now, all WeBWorK files are located under As root, create a # mkdir /var/local/webwork As a regular user, move the courses directory into your new > mv /usr/local/webwork/courses /var/local/webwork Now, a slight modification to the structure of the WeBWorK system structure must be made. The directory > rm -r /usr/local/webwork/system/courses Also, it is a good idea to "crosslink" the courses and system directory so that we can easily move between them without typing out the absolute paths: > ln -s /var/local/webwork/courses /usr/local/webwork Some WeBWorK documentation will instruct you to maintain course symlinks in Step 8: Obtaining Additional SupportOnline support is available at: http://webwork.math.rochester.edu/docs/ |