Forum archive 2000-2006

Michael Gage - Migration Instructions to WeBWorK 2.0

Michael Gage - Migration Instructions to WeBWorK 2.0

by Arnold Pizer -
Number of replies: 0
inactiveTopicMigration Instructions to WeBWorK 2.0 topic started 5/30/2003; 4:45:21 PM
last post 5/30/2003; 4:45:21 PM
userMichael Gage - Migration Instructions to WeBWorK 2.0  blueArrow
5/30/2003; 4:45:21 PM (reads: 688, responses: 0)

Important!!!

June 17, 2003<

 

The notes on this page have been replaced. The new installation procedures are similar but simpler. For help in migrating from a current WeBWorK2.0 CVS system to the latest version, post comments to this website or write gage@math.rochester.edu.

June 6, 2003

Already some changes. These are designed to make it easier to keep the macro files for webwork1.8 and webwork2.0 in sync. Problems should run on either system. The additions and changes to the apache httpd.conf file are in red.

The big change is to set up a pg directory at the same level as webwork-modperl. This directory will contain the macro files and the .pm files used by the PG language in either webwork1.8 or webwork2.0. See directions below. This is pretty easy.

Finally you need to redo the global.conf file. The easiest way I believe is to move your current global.conf to global.save (mv global.conf global.save) and then copy global.conf.dist to global.conf (cp global.conf.dist global.conf). Now follow the directions below to customize the global.conf file. -- You can peak at your global.save file to use as a guide.

-- June 5, 2003

OK. For those of you willing to participate at the bleeding edge -- you can now download WeBWorK 2.0 via CVS. Thanks in advance for your help.

Instructions for migrating to WeBWorK 2.0

These are intended particularly for interns working at Rochester. Others are willing to try these procedures if you wish, or you can wait a few days until the instructions are debugged. WeBWorK2 is pretty stable from the student users point of view. The tools used by the instructor are just becoming useable and are still somewhat unstable. For the next month we'll ask that anyone wishing to try out WeBWorK 2.0 obtain the scripts via a CVS (as per the instructions in this document) so that they can easily update to obtain the latest bug fixes as they are made.

These instructions assume that you are already running WeBWorK 1.8, and details how to install WeBWorK 2.0 so that it runs in parallel for the same courses.

A second step in the migration (not yet described in detail) will allow you to use a mysql database instead of the GDBM database currently in use. Using the mysql database will increase the options available for the instructor, as well as the speed on large data sets.

In order to use WeBWorK 2.0 you MUST have mod_perl enabled on your apache server. (If you don't know what this means, then wait a bit before trying out WeBWorK 2.0)

I'll assume three things:

  1. your current webwork 1.8 system has the structure .../topDir/webwork/system/.... and that system directory has sub directories such as cgi, courses,courseScripts, scripts, and so forth.
  2. Similarly your course will be contained in a structure ../courses/myCourse/... and the myCourse directory will contain webworkCourse.ph, html, templates, and so forth. The templates directory will contain a macros directory (which will probably be empty). (In many cases, following the standard setup for WeBWorK1.8, the course directory will be at ../topDir/webwork/courses/myCourse, that is the courses and sytem directory are siblings.
  3. Finally the links to your courses are of the form http:\//myMachine/myCourse/. For example you might have a directory called ../htdocs/ which is the home directory for your apache server and which contains links to the html directory of myCourse:
    ls -l myCourse ---> ...../courses/myCourse/html/

Here we go.

First we create a cvs repository

  1. cd topDir/webwork # (get to your webwork directory)
  2. In order to install the webwork-modperl scripts you will need write permissions in this directory.
  3. cvs -d :pserver:anonymous@webwork-db.math.rochester.edu:/var/cvs/system checkout webwork-modperl
  4. This will create a directory webwork-modperl inside topDir/webwork
  5. Next we create a directory for pg
  6. cvs -d :pserver:anonymous@webwork-db.math.rochester.edu:/var/cvs/system checkout pg

Make sure that these files can be read by the apache daemon

The directories have 744 permissions when they are created. We need to make sure that the directories can all be executed by the apache daemon and read by it as well.

  1. While still in topDir/webwork type:
    1. chmod -R go+X webwork-modperl
    2. chmod -R go+X pg
    3. This adds execution permissions to all of the directories in the webwork-modperl tree and the pg tree, allowing access to the files in the webwork-modperl directories. The capitalization is important (as is usual in unix commands).
    4. We are using relatively lax security, since anyone can now read these files. ("Tightening the permission structure" -- to be written)
  2. To determine the groups which your apache server belongs to type
    ps -aux |grep httpd
    to get a listing of processes which are running. Look for something like  
    wwhttpd 72270 0.0 0.1 1896 1384 ?? I 1:00AM 0:00.01 /usr/local/sbin/httpd
    wwhttpd 72274 0.0 0.1 1908 1392 ?? S 1:02AM 0:00.04 /usr/local/sbin/httpd

    This tells me that the apache daemon is named wwhttpd on our machine
    Next type
    groups wwhttpd
    webwork MTH161 MTH141A MTH140A MTH140L MTH141 MTH142 MTH143 ....

    Our daemon belongs to many course groups and also to one general group webwork. For WeBWorK 2.0 the daemon only needs to belong to one group -- in our case webwork
    You may need to consult with whomever has been setting up groups for your WeBWorK 1.8 course.
  3. From the topDir/webwork directory set the group for the directory webwork-modperl to webwork
    1. chgrp -R webwork webwork-modperl
      ls -l
      drwxr-xr-x 14 gage webwork 512 May 31 12:33 webwork-modperl/
      chgrp -R webwork pg
  4. Set write permission for the logs directory
    1. % cd webwork-modperl
      % ls -l
      total 24
      drwxr-xr-x 2 gage webwork 512 May 31 12:33 CVS/
      drwxr-xr-x 3 gage webwork 512 May 31 12:33 bin/
      drwxr-xr-x 3 gage webwork 512 May 31 12:33 conf/
      drwxr-xr-x 4 gage webwork 512 May 31 12:33 courses/
      drwxr-xr-x 3 gage webwork 512 May 31 12:33 doc/
      drwxr-xr-x 4 gage webwork 512 May 31 12:33 htdocs/
      drwxr-xr-x 5 gage webwork 512 May 31 12:33 lib/
      drwxr-xr-x 3 gage webwork 512 May 31 12:33 logs/
      drwxr-xr-x 4 gage webwork 512 May 31 12:33 tests/
      drwxr-xr-x 3 gage webwork 512 May 31 12:33 tmp/
    2. % chmod g+w logs # make the directory writeable for the group webwork
    3. % ls -l # check that it worked!
      drwxrwxr-x 3 gage webwork 512 May 31 12:33 logs/

Configure WeBWorK 2.0

-- to make sure that it knows where to find files. This is done by creating global.conf in the conf (configure) directory.

  1. % cd conf
    %ls
    CVS/
    hardcopySetFooter.pg
    barebones.template
    hardcopySetHeader.pg
    classic.template
    httpd-wwmp-header.conf.dist
    global.conf.dist
    httpd-wwmp.conf.dist
    hardcopyPostamble.tex
    screenSetHeader.pg
    hardcopyPreamble.tex
    system.template
    hardcopyProblemDivider.tex
    test.template
    hardcopySetDivider.tex
    ur.template
  2. Make a copy of the global.conf.dist file at global.conf and edit it (with your favorite unix editor)
    1. cp global.conf.dist global.conf
      nano global.conf (# or pico global.conf might work, or use emacs or vi :-) )
    2. The variable $webworkRoot will point to the directory topDir/webwork/webwork-modperl which you have created. You should not need to change any of these values when using the default configuration. If you change the directory structure of WeBWorK for some reason you may also have to make changes here.
  3. Initially you will only need to make one change (if your directory structure is as described in the instructions above).
    previously you made two changes here
    1. Change addresses for oldProf in the structure  
      %webworkURLs = (
      root => "$webworkURLRoot",
      home => "/webwork2_files/index.html",
      htdocs => "/webwork_files",
      docs => "http://webhost.math.rochester.edu/webworkdocs/docs",
      oldProf => "/webwork-old/profLogin.pl",
      );

      to  
      %webworkURLs = (
      root => "$webworkURLRoot",
      home => "/webwork2_files/index.html",
      htdocs => "/webwork2_files",
      docs => "http://webhost.math.rochester.edu/webworkdocs/docs",
      oldProf => "http://your.host.edu/cgi-bin/system/cgi/profLogin.pl",
      );
    2. The oldProf url should just like the url that WeBWorK 1.8 uses on your system when you go to the "professor Page" to edit classlists, butild sets and so forth.
    3. The structure for the external programs used by webwork may also need adjusting
      1.  
        %externalPrograms = (
        mkdir => "/bin/mkdir",
        tth => "/usr/local/bin/tth",
        pdflatex => "/usr/local/bin/pdflatex",
        latex => "/usr/local/bin/latex",
        dvipng => "/usr/local/bin/dvipng -mode ljfivemp -D600 -Q6 -x1000.5 -bgTransparent",
        gif2eps => "$webworkDirs{bin}/gif2eps",
        png2eps => "$webworkDirs{bin}/png2eps",
        gif2png => "$webworkDirs{bin}/gif2png",
        );
    4. You can insure that the external programs have been installed on your machine by typing
      1.  
        which tth
        /usr/local/bin/tth
        which pdflatex
        /usr/local/bin/pdflatex
        which dvipng
        /usr/local/bin/dvipng

Configure the Apache server

Now we have to tell the apache server where to find the webwork 2.0 files. It helps to have someone who has set up and restarted the apache server help out at this point.
  1. First find the apache config file. Usually called httpd.conf and found perhaps in /etc/httpd/ or in our case /usr/local/etc/apache
  2. Check that httpd.conf contains these two lines (uncommented). The lines are in two different sections of http.conf
  3. LoadModule perl_module libexec/httpd/libperl.so
    AddModule mod_perl.c
  4. If these lines are there, but commented out with a #, just uncomment them. If they are not there at all then you first need to build an apache daemon which will run mod_perl. That is beyond the scope of this note.
  5. Assuming that all is well, we need to add these two code fragments to the httpd.conf file. (These directions are also available on the page how to use CVS with WeBWorK2.) You will see similar code fragments in the file already. Add the fragment below near similar initialization fragments making sure that you respect the if/endif structure of the file. You will need to modify the boldface path names to fit your installation.
  6.  
    <IfModule mod_perl.c>
    PerlFreshRestart On
    <Location /webwork2>
    SetHandler perl-script
    PerlHandler Apache::WeBWorK
    PerlSetVar webwork_root topDir/webwork/webwork-modperl
    PerlSetVar pg_root topDir/webwork/pg
    <Perl>
    use lib 'topDir/webwork/webwork-modperl/lib';
    #use lib 'topDir/webwork/webwork-modperl/pglib';
    use lib 'topDir/webwork/pg/lib';
    </Perl>
    </Location>
    </IfModule>
  7. We also need to define url link for the accessing images and such like.
  8.  
    Alias /webwork2_files/ topDir/webwork/webwork-modperl/htdocs/
    # Alias /webwork2_courses/ ......htdocs/ -- this alias can be removed entirely
    <Directory "topDir/webwork/webwork-modperl/htdocs">
    Options Indexes FollowSymLinks MultiViews
    AllowOverride None
    Order allow,deny
    Allow from all
    </Directory>
  9. The alias allows you to find installation wide information stored in the webwork-modperl/htdocs directory. This includes the index.html file and courses which contains links to the html directories of each of your courses.
  10. # This paragraph is no longer, as they say, "operative". Ignore it : The second alias should point to the directory where you store the links to your course html directories. For example the link to myCourse/html described above. Because the second directory already exists, no "Directory" section is required for it. The first alias, however points to a new directory and the \"Directory" directive tells the rules for connecting to it.
  11. Finally here is a little test module that will help with trouble shooting which is worth installing.
  12.  
    # status test
    <Location /status>
    SetHandler perl-script
    PerlHandler Apache::Status
    </Location>

Restart the Apache server

Before doing this locate the location of the apache error log.

You can search httpd.conf for ErrorLog. Our error log is stored at /ww/logs/error_log on one machine and /var/log/error_log on another.

In a separate window issue the command

 

tail -f /ww/logs/error_log

(use your own path to the error log) to view the last 20 lines or so of errors issued by the apache server.

The restart command is called apachectl (apache control) and is probably in /usr/local/sbin

 

sudo /usr/local/sbin/apachectl graceful

Tells the apache server to shutdown and restart gracefully.

In the window showing the contents of the error_log you should see a flurry of activity. The last messages should not be error messages. If they are, try to decipher them. They might indicate a typo in http.conf which you have to correct.

Another possibility is that one or more perl modules have not been installed. (Mail::Sender.pm is the most likely culpret). These modules are all common perl modules and can be obtained and installed from CPAN. ("Instructions on installing CPAN modules" to be written.)

Refer to this error log listing whenever something funny happens. There may be a useful error message.

Testing the server

Open a browser go the url http://your.host.edu/status. If this works it should give a number of links to information about your apache server, includng which modules are installed.

Next type the url http://your.host.edu/webwork2. This should give a response of Welcome to WeBWorK2.0 at the University of Rochester

For the fun of it go to topDirs/webwork/webwork-modperl/ and edit the file index.html, replacing the University of Rochester by your own institution. This is just an html file, you can add anything else you want. Test that it works. You don't have to restart the server.

Hooking up to your current WeBWork 1.8 course -- this section has changed. Please read!!

We now know that WeBWorK2.0 system is working and connected. It remains to connect the WeBWorK1.8 courses to WeBWorK2.0

There are two connection points to WeBWorK2.0

  1. A URL of the form http://www.myyour.host.edu/webwork2/myCourse will access myCourse if it is in the directory topDir/webwork/webwork-modperl/courses/myCourse In fact that directory already contains a minimal course called test_course so http://your.host.edu/webwork2/test_course should give you a login page. (If you enter a login name you will get an error, because no database of users has been built for this course yet. Just getting the login message is enough to confirm that this link is correctly set up.)
  2. The second link is for URLs of the form http://your.host.edu/webwork2_files/myCourse which will access the links in topDir/webwork/webwork-modperl/htdocs/courses. The htdocs/courses directory contains symlinks to the html directory in each course. In our case
    1. ls -l htdocs/courses
    2. should give
    3. test_course --> topDir/webwork/webwork-modperl/courses/test_course/html

Notice that the first directory, topDir/webwork/webwork-modperl/courses corresponds to the directory ../courses mentioned as the second of the three assumptions I made at the top of this page. It is the directory that contains all of your WeBWorK1.8 courses. We will make a symlink between the two directories. While in the directory webwork-modperl type

 
mv courses courses.save
ln -s .../courses courses

We moved the webwork-modperl/courses directory out of the way (saving it) so that we could construct a symlink between the webwork-modperl/courses link (alias) and the .../courses directory containing the WeBWorK 1.8 courses. The "test_course" URL will no longer work, since it is now in courses.save instead of in courses.

Next transfer to webwork_modperl/htdocs (cd htdocs)

 
mv courses courses.save
ln -s ..../htdocs courses

We have symlinked the topDir/webwork/webwork-modperl/htdocs/courses directory to the .../htdocs in your WeBWorK1.8 setup.

The .../htdocs directory itself contains a link to .../courses/myCourse/html

Testing the hook-up

Type the url http://www.yourhost.edu/webwork2_files/myCourse (making the obvious substitutions for your server and your course)

You should get the login page for your existing WeBWorK1.8 course! If you don't, then there might be a problem with the symlink between the directory ..topDir/webwork/webwork-modperl/htdocs/courses and the .../htdocs directory. Check also that the .../htdocs directory has a symlink called myCourse which points to .../courses/myCourse/html. It is a common mistake to forget the last html in the link.

The other connection that might be at fault is the Alias entry in http.conf (Alias /webwork2_files/ ...topDir/webwork/webwork-modperl/htdocs/ )

Assuming all is well so far type the url http://your.host.edu/webwork2/myCourse where myCourse is the name of one of your existing courses. You should get a login screen and be able to view your course. If this doesn't work at all, check the <Location /webwork2> directive in the httpd.conf file. Check also the permissions on the files and directories in webwork-modperl. Remember that the apache server must be able to execute the directories in order to read the files inside.

If you get an error screen saying something like: "Can't read .../macros/IO.pl" then either the PerlSetVar pg_root topDir/webwork/pg is not pointing to the topDir/webwork/pg directory or the server does not have permission to read the files in that directory (Again remember that it must be able to execute the directories in order to read the files inside.)

The access to the professor pages is still being developed. When you click on the "instructor" link in the left maargin you will be taken to a page where you can use the "professor pages" from WeBWorK 1.8 to edit your course (the third and fourth links) or you can use the second link to edit problem sets. The first link, to edit users is not yet very functional. If the third and fourth links don't work check the value given to oldProf in the global.conf file.

You can report bugs using the bug link in the upper left corner. The first time you do this you will need to login and receive a password via e-mail. Once logged in bugzilla will set a cookie and you will be taken directly to the page for reporting bugs.

Speeding up large classes.

You don't HAVE to make any configuration changes in your course directory. However one change will speed up the listing of problem sets in large courses:

Inside your course myCourse (this directory contains webworkCourse.ph, templates, DATA, etc.) create a file course.conf

In side course.conf place the lines
 
$dbLayout{set}->{params}->{globalUserID} = "yourID";
# yourID is the instructor's loginID for the course (or whoever is responsible for building sets and maintaing the course.)
$dbLayout{problem}->{params}->{globalUserID} = "yourID";

There are other customization which can be made in this file to override those in global.conf, but we'll come to those later.

Post comments in reply to this note -- let me know what worked and what didn't.

-- Mike Gage

<| Post or View Comments |>