Parent Directory
| 
Revision Log
add comment about noserpage switch
1 <html> 2 <head> 3 <title>Installing WeBWorK on a Linux System</title> 4 </head> 5 <body> 6 <h1>Installing WeBWorK on a Linux System</h1> 7 <p> 8 For WeBWorK version 1.8<br> 9 Samuel Hathaway <sh002i@math.rochester.edu><br> 10 Arnold Pizer <apizer@math.rochester.edu> 11 </p> 12 <hr> 13 <p>This document will guide you through the installation of WeBWorK and its 14 support packages. We assume the reader has prior experience with UNIX system 15 administration tasks such as compiling software, configuring the Apache server, 16 etc.</p> 17 <p>Usually the installation of WeBWorK proceeds without difficulty. If there 18 is difficulty, almost always it involves the installation of required packages 19 (apache, perl and perl modules, latex2html, dvipng, etc.) rather than WeBWorK itself. 20 While all required packages are standard and well supported, there are a lot of 21 dependencies and problems can arrise. The document 22 <em>Installing WeBWorK on a Red Hat Linux 8.0 System</em> gives detailed instructions 23 for that system and might provide useful hints for other systems.<p> 24 If you do not want to follow the 25 instructions below, Bill Ziemer <wziemer@csulb.edu> has posted a makefile 26 which will install a separate configured copy of all required packages on your system. 27 Connect to <a 28 href="http://http://webwork-db.math.rochester.edu/cgi-bin/cvsweb.cgi/">http://webwork-db.math.rochester.edu/cgi-bin/cvsweb.cgi/</a>, 29 select the CVS Root <code>CSLB</code> and download 30 <code>webwork_VERSION_SUBVERSION-MONTH-DAY-YEAR_install.tar.gz</code>. 31 <p>Most steps in the installation process can be done as a normal user. 32 However, some steps must be done as the root user. While attempts have been made 33 to minimize the number of commands that must be executed as root, it is still 34 important to be cautious whenever using the root account.</p> 35 <p>Within this document, commands given by root will be prefixed with "#" while 36 commands given by a normal user will be prefixed with ">". Note that throughout 37 this document, all references to a "normal user" refer to the same normal user. 38 If you have <code>sudo</code> installed, it is recommended that you use it for 39 the root commands. Otherwise, leave two terminal windows open — one as root 40 and one as a normal user.</p> 41 <hr> 42 <h2>Step 1: Installing perl</h2> 43 <p>On many Linux distributions, the distribution version of perl is not adequate 44 for use with WeBWorK. Specifically, perl must be compiled with GDBM database 45 support. Whether this is so can be determined in one of two ways:</p> 46 <p>For static linkage, check the <code>libs=</code> line in the perl version 47 information. You should see an item <code>-lgdbm</code>. For dynamic linkage, 48 check the output of <code>ldd</code> for perl. You should see an item 49 <code>libgdbm</code>.</p> 50 <pre> 51 > perl -V | grep libs= 52 libs=-lm -lc -lcrypt 53 </pre> 54 <p>In this case, libm, libc, and libcrypt are compiled into perl.</p> 55 <pre> 56 > ldd `which perl` 57 /usr/bin/perl: 58 libperl.so.3 => /usr/lib/libperl.so.3 (0x28066000) 59 libm.so.2 => /usr/lib/libm.so.2 (0x280fe000) 60 libcrypt.so.2 => /usr/lib/libcrypt.so.2 (0x28119000) 61 libmd.so.2 => /usr/lib/libmd.so.2 (0x2812e000) 62 libc.so.4 => /usr/lib/libc.so.4 (0x28138000) 63 libutil.so.3 => /usr/lib/libutil.so.3 (0x281cd000) 64 </pre> 65 <p>In this case, libperl, libm, libcrypt, libmd, libc, and libutil are linked to perl.</p> 66 <p>If GDBM is not present in either of these outputs, perl needs to be 67 recompiled with GDBM support. The perl compilation process will automatically 68 compile GDBM support if the GDBM libraray is detected. Most Linux distributions 69 come with the GDBM library. It is called <code>libgdbm</code> and is usually 70 found in <code>/usr/lib</code> or <code>/usr/local/lib</code>. If you need to 71 install the GDBM library, it is available at <a 72 href="http://www.gnu.org/software/gdbm/">http://www.gnu.org/software/gdbm/</a>. 73 Please refer to the perl source code distribution site at <a 74 href="http://www.perl.com/">http://www.perl.com</a> for 75 information about compiling and installing perl (click on Downloads, Source Code). 76 Hint: get the stable.tar.gz file, extract it with the command 77 <pre> 78 tar -xzf stable.tar.gz 79 </pre> 80 and then read the README file. 81 </p> 82 <p>Please note that if you recompile perl, you may have to be careful about 83 maintaining two copies of perl on your system. When you set up WeBWorK, the 84 setup script will try to guess where your perl is. However, it may guess the 85 "old" version of perl if it comes before the "new" one in your path. Make sure 86 the correct path to perl is used when setting up WeBWorK. For convenience, you 87 may want to remove the original version of perl. The perl install process will 88 ask you if you want to do 89 this.</p> 90 <hr> 91 <h2>Step 2: Installing additional packages</h2> 92 <p> You now have to install additional perl modules needed for WeBWorK. These 93 are HTML::Parser, Net::SMTP, MIME::Base64, and GD. You can use CPAN to install 94 the first three.</p> 95 <p>If 96 this is the first time you're run CPAN, you will be asked to configure 97 it (you can say "no" and it will autoconfigure). As root, run the command</p> 98 <pre> 99 # perl -MCPAN -e shell 100 cpan> install HTML::Parser Net::SMTP MIME::Base64 101 </pre> 102 <p>If there are prerequisites which need to be installed, allow CPAN to "prepend 103 prerequisites to the installation queue". CPAN may prompt you for configuration 104 settings for the modules you are installing.</p> 105 <p> Sometimes a module may not install properly. 106 To verify that a module, e.g. Net::SMTP, has been installed successfully run the 107 the command</p> 108 <pre> 109 > perl -MNet::SMTP -e 'print "installed\n"' 110 </pre> 111 <p>You should get the message:</p> 112 <pre> 113 installed 114 </pre> 115 <p>if Net::SMTP was installed successfully and an error message if it was not. </p> 116 <p>If you get an error message, you can force cn install by using the commands</p> 117 <pre> 118 # perl -MCPAN -e shell 119 cpan> force install Net::SMTP 120 </pre> 121 <p> This may or may not be appropiate depending on what the problem is. For example, 122 at one time (Fall 2001) the installation Net::SMTP failed because it tested for 123 components that were not part of the installation package. In this case the appropiate 124 solution was to use force.</p> 125 <p>In a similar manner, you can test whether the other modules 126 HTML::Parser, and MIME::Base64 (and GD, see below) were installed successfully. If you 127 do not run these tests now, at least remember them in case you get error messages concerning 128 modules later.</p> 129 130 <p> You also have to install the GD module. Currently (Fall 2002) if you use CPAN to install GD, it will 131 install the 2.01 version of GD.pm which requires the beta 2.0.1 version of gd. 132 Unfortunately there is a known bug in gd 2.0.1 which prevents it from drawing horizontal dashed 133 lines. We recommend using gd 1.8.4 and GD 1.33. gd is probably on your system. For GD, go to 134 <a href="http://stein.cshl.org/WWW/software/GD/">http://stein.cshl.org/WWW/software/GD/</a>. 135 <p>As a normal user, download the tar/gzip archive for version 1.33 (or 1.29) and untar it:</p> 136 <pre> 137 > tar -xzf GD.pm.tar.gz 138 </pre> 139 then cd to the <code>GD-1.33</code> subdirectory and follow the installation instructions 140 in the README file. Usually this means running the commands:</p> 141 <pre> 142 > perl Makefile.PL (select JPEG but not FreeType or XPM support for WeBWorK) 143 > make 144 </pre> 145 <p>Then, as root, install it. 146 <pre> 147 # make install 148 </pre> 149 If you have difficulty, read the README file and also look at the special instructions 150 <em>Installing WeBWorK on a Red Hat Linux 8.0 System</em> which explain 151 the changes necessary to install GD on that operating system. 152 </p> 153 <p>Next, you will need to install several support programs used by WeBWorK. Most 154 distributions include packaged versions of these programs, but they are not 155 always installed by default. Consult the documentation for your distribution to 156 find out if you can use a prepackaged version. If you wish, you can also install 157 from source:</p> 158 <ul> 159 <li>Apache: <a href="http://httpd.apache.org/">http://httpd.apache.org/</a></li> 160 <li>Ghostscript: <a href="http://www.cs.wisc.edu/~ghost/">http://www.cs.wisc.edu/~ghost/</a></li> 161 <li>LaTeX2HTML: <a href="http://www.latex2html.org/">http://www.latex2html.org/</a></li> 162 <li>Netpbm: <a href="http://netpbm.sourceforge.net/">http://netpbm.sourceforge.net/</a></li> 163 <li>teTeX: <a href="http://www.tug.org/teTeX/">http://www.tug.org/teTeX/</a></li> 164 <li>dvipng: <a href="http://hobbes.la.asu.edu/webwork-stuff">http://hobbes.la.asu.edu/webwork-stuff 165 </a></li> 166 </ul> 167 <h3>LaTeX2HTML</h3> 168 <p>LaTeX2HTML is necessary to use the 'typeset' display mode when viewing 169 problems on the screen. If you're just evaluating WeBWork or don't wish to use 170 'typeset' mode, you can skip this section.</p> 171 <p>LaTeX2HTML has some dependancies of its own. Consult the LaTeX2HTML 172 Requirements Page at <a href="http://www- 173 texdev.mpce.mq.edu.au/l2h/docs/manual/Snode2_mn.html">http://www- 174 texdev.mpce.mq.edu.au/l2h/docs/manual/Snode2_mn.html</a> for more 175 information.</p> 176 <p>Only LaTeX2HTML version 96.1 and 98.1p1 have undergone extensive testing with 177 WeBWorK. WeBWorK ships with latex2html.init files for each if these versions. 178 However, the init file for version 98.1p1 appears to work with later 179 versions.</p> 180 <p>LaTeX2HTML may be broken with respect to the WeBWorK system when installed. 181 To fix it, make sure the following configuration variables are set as follows in 182 the LaTeX2HTML configuration file, which may be called 183 <code>latex2html.config</code> or <code>l2hconf.pm</code> and may be located in 184 <code>/etc</code> or in the LaTeX2HTML directory, depending on the version and 185 how it was installed.</p> 186 <pre> 187 $PK_GENERATION = 1 188 $DVIPS_MODE = 'toshiba' 189 $METAFONT_DPI = 180 190 </pre> 191 <h3>Netpbm</h3> 192 <p>Netpbm versions before 9.11 cause black borders to appear to the left of and 193 below images generated by LaTeX2HTML. To fix this, apply the patches detailed 194 at: <a href="http://tug.org/pipermail/latex2html/2001- 195 May/001112.html">http://tug.org/pipermail/latex2html/2001- 196 May/001112.html</a></p> 197 <h3>TTH</h3> 198 <p>WeBWorK uses TTH, a C program which typesets TeX as HTML, using tables and 199 other markup. TTH is necessary to use the 'formatted-text' display mode when 200 viewing problems on the screen. If you're just evaluating WeBWork or don't wish 201 to use 'formatted-text' mode, you can skip this section.</p> 202 <p>TTH cannot be distributed with WeBWorK because of licencing issues. It can be 203 obtained from <a 204 href="http://hutchinson.belmont.ma.us/tth/">http://hutchinson.belmont.ma.us/tth/ 205 </a>. If you can, download a precompiled binary. Otherwise, download the source 206 and the following other packages:</p> 207 <ul> 208 <li>C libarary headers: <a href="http://www.gnu.org/software/libc/">http://www.gnu.org/software/libc/</a></li> 209 <li>GCC: <a href="http://gcc.gnu.org/">http://gcc.gnu.org/</a></li> 210 </ul> 211 <p>As a normal user, download TTH to your home directory. Then untar, build, and 212 install it with the following commands:</p> 213 <pre> 214 > tar -xzf tth_C.tgz 215 > cd tth_C 216 > gcc -o tth tth.c 217 </pre> 218 <p>Then, as root, install it. 219 <pre> 220 # cp tth /usr/bin/ 221 </pre> 222 223 <h3>dvipng</h3> 224 <p>dvipng is necessary to use the 'typeset2' display mode when viewing 225 problems on the screen. If you're just evaluating WeBWork or don't wish to use 226 'typeset2' mode, you can skip this section.</p> 227 <p>dvipng produces typeset images identical in quality to those produced by LaTeX2HTML. 228 It is much faster than LaTeX2HTML and WeBWorK will probably use it in place of LaTeX2HTML 229 in the future. Currently it is still in the experimental stage. For information on 230 obtaining and installing dvipng visit John Jones's site 231 <a 232 href="http://hobbes.la.asu.edu/webwork-stuff">http://hobbes.la.asu.edu/webwork-stuff 233 </a>. </p> 234 235 <hr> 236 <h2>Step 3: Configuring apache</h2> 237 <p><strong>Note:</strong> Since the locations of apache's document root and cgi- 238 bin directories are distribution dependant, I will use 239 <code>$DOCUMENT_ROOT</code> and <code>$CGI_BIN</code> to refer to these 240 locations. The actual locations are defined in the apache configuration file, 241 see below. If you wish, you can set these two variables in your shell so that 242 you can type them directly.</p> 243 <p>Your apache configuration may need to be tweaked to allow WeBWorK to function 244 properly. First, you must make sure that apache runs as a real system user and 245 in a real system group, rather than as <code>nobody</code> in 246 <code>nogroup</code>. This is becasue the WeBWorK scripts need to be able to 247 modify certain course files on the disk. Some distributions of apache already 248 run as a real system user. If so, you may skip the creation of a new user and 249 group, and use the existing ones. If you need to change apache's user and group, 250 first create a new user and group called <code>wwserver</code>:</p> 251 <pre> 252 # useradd wwserver 253 # groupadd wwserver 254 </pre> 255 <p>Then, in the apache configuration file <code>httpd.conf</code>, usually found 256 in <code>/etc/apache</code> or <code>/usr/local/etc/apache</code>, find the 257 following lines:</p> 258 <pre> 259 User nobody 260 Group nogroup 261 </pre> 262 <p>Change them so that they list <code>wwserver</code> as the user and group:</p> 263 <pre> 264 User wwserver 265 Group wwserver 266 </pre> 267 <p>There are two ways that the webserver can be given access to WeBWorK files. 268 The first is to add an explicit <code>ScriptAlias</code> to the WeBWorK cgi 269 directory in your apache configuration (this is the method we recommend). The 270 second is to create a symlink pointing from your existing cgi-bin directory to 271 the WeBWorK cgi directory. If you chose to use symlinks, you will have to 272 make sure that the <code>FollowSymLinks</code> option is on for the document 273 root and cgi-bin 274 directories.</p> 275 <p>In either case, your document root must have <code>FollowSymLinks</code> 276 turned on. In one of your apache configuration files, find the directory stanza 277 for the document root. It will look roughly like this:</p> 278 <pre> 279 <Directory $DOCUMENT_ROOT> 280 Options <strong>FollowSymLinks</strong> Indexes Includes 281 AllowOverride None 282 Order allow,deny 283 Allow from all 284 </Directory> 285 </pre> 286 <p>The important line is <code>Options FollowSymLinks</code>. Make sure that 287 that is present. It is okay if other options are present too. If you chose to 288 symlink to the WeBWorK cgi-bin directory, also make sure that the directory 289 stanza for your cgi-bin directory has <code>FollowSymLinks</code> turned on:</p> 290 <pre> 291 <Directory $CGI_BIN> 292 Options <strong>FollowSymLinks</strong> ExecCGI 293 AllowOverride None 294 Order allow,deny 295 Allow from all 296 </Directory> 297 </pre> 298 <p>If you chose to use a <code>ScriptAlias</code> to link apache to the WeBWorK 299 cgi-bin directory, you will need to add the following to your apache 300 configuration:</p> 301 <pre> 302 ScriptAlias /cgi-bin/webwork/system/ "/usr/local/webwork/system/cgi/" 303 <Directory /usr/local/webwork/system/cgi/> 304 Options ExecCGI 305 AllowOverride None 306 Order allow,deny 307 Allow from all 308 </Directory> 309 </pre> 310 <p>Make sure that these lines go before any existing <code>ScriptAlias</code> 311 directives. Remember to restart apache after making these changes.</p> 312 <hr> 313 <h2>Step 4: Installing the WeBWorK package</h2> 314 <p>WeBWorK can be downloaded from following URL: 315 http://webhost.math.rochester.edu/downloadwebwork/ . Click on the Download Files 316 link on the left side panel. </p> 317 <p>If you haven't already, you need to register to be able to download files. 318 The WeBWorK archives are named in the following form:</p> 319 <pre> 320 webwork_VERSION_SUBVERSION-MONTH-DAY-YEAR.tar.gz 321 templates_VERSION_SUBVERSION-MONTH-DAY-YEAR.tar.gz 322 </pre> 323 <p>The <code>webwork</code> archive contains the webwork system files and the 324 blankCourse. The <code>templates</code> archive contains the problem set 325 templates, and is updated more often than the <code>webwork</code> archive 326 is.</p> 327 <p>As a normal user, download the latest versions of the webwork archive. Untar 328 the WeBWorK archive using:</p> 329 <pre> 330 > tar -xzf webwork_VERSION_SUBVERSION-MONTH-DAY-YEAR.tar.gz 331 (replacing the file name with the file you actually have.) 332 </pre> 333 <p>This results in the creation of a webwork_VERSION_SUBVERSION-MONTH-DAY-YEAR 334 directory which contains several readme files and the <code>webwork</code> 335 directory, which contains the actual webwork system. First <code>cd</code> to 336 the new directory</p> 337 <pre> 338 cd webwork_VERSION_SUBVERSION-MONTH-DAY-YEAR 339 </pre> 340 Next we must copy the 341 <code>webwork</code> directory to <code>/usr/local</code>. As root, run:</p> 342 <pre> 343 # mv webwork /usr/local 344 </pre> 345 <p>The WeBWorK files are now in their initial location. Next, a user group must 346 be created for users who are allowed to modify all WeBWorK files. It is 347 recommended that this group be named <code>wwadmin</code>. As root, execute:</p> 348 <pre> 349 # groupadd wwadmin 350 # usermod -G wwadmin,<othergroups> <username> 351 </pre> 352 <p><strong>Note:</strong> The <code>usermod</code> command will remove a user 353 from any groups not specified with the <code>-G</code> switch. Make sure to list 354 all the groups to which a user belongs when using this command. This manual uses 355 <code>user{add,mod,del}</code> and <code>group{add,mod,del}</code> as these 356 utilities are available on most linux systems. It is often easier to use a more 357 user-friendly tool provided with your distribution. Older versions of Red Hat provide 358 <code>linuxconf</code>, which may not be installed by default. New versions have the 359 Red Hat User Manager. Debian provides 360 <code>adduser</code> and <code>addgroup</code>.</p> 361 <p>You can add any number of users with the second command, replacing 362 <code><username></code> with the name of the user to add. Make sure that 363 you add the user account that you are going to be using to finish setting up the system.</p> 364 <p>We'll make a webwork directory in apache's document root to contain a 365 symlink to each course. We'll also give you ownership of this directory 366 so you can add courses later without becoming root. We will also change permissions so 367 that any user in the group <code>wwadmin</code> can do the same. 368 As root, type the following:</p> 369 <pre> 370 # mkdir $DOCUMENT_ROOT/webwork 371 # chown <username>.wwadmin $DOCUMENT_ROOT/webwork 372 # chmod 775 $DOCUMENT_ROOT/webwork 373 </pre> 374 <p>If you chose not to add a <code>ScriptAlias</code> directive to your apache 375 configuration, you also need to add a webwork directory to apache's cgi-bin 376 directory.</p> 377 <pre> 378 # mkdir $CGI_BIN/webwork 379 # chown <username>.wwadmin $CGI_BIN/webwork 380 # chmod 775 $CGI_BIN//webwork 381 </pre> 382 <p>We need to allow apache access to WeBWorK's html directory. As root, type:</p> 383 <pre> 384 # ln -s /usr/local/webwork/system_html $DOCUMENT_ROOT/webwork_system_html 385 </pre> 386 <p>Again, if you didn't add a <code>ScriptAlias</code> directive to your apache 387 configuration, you also need to allow apache access to WeBWorK's cgi 388 directory:</p> 389 <pre> 390 > ln -s /usr/local/webwork/system/cgi $CGI_BIN/webwork/system 391 </pre> 392 <p>The next step uses your normal user account, and requires membership in the 393 wwadmin group. Thus, you'll need to log out of this account and then log back 394 in. Depending on your setup, you may have to log out of X for changes to take 395 effect. Next, we'll set the group of the entire WeBWorK system to 396 <code>wwadmin</code> and give it some default permissions. As a normal user:</p> 397 <pre> 398 > chgrp -R wwadmin /usr/local/webwork/ 399 > chmod -R 775 /usr/local/webwork/ 400 </pre> 401 <p>These permissions are very lax, but that will be fixed when we run the setup 402 script. As a normal user:</p> 403 <pre> 404 > cd /usr/local/webwork/system 405 > perl system_webwork_setup.pl 406 </pre> 407 <p>This script will ask you several questions about the environment in which 408 WeBWorK will be running. Read the information given with each choice carefully. 409 Recommended choices are given in brackets, and can be accepted by pressing enter 410 rather than typing a response.</p> 411 <p>In order to use logging, you need to give the web server write access to the 412 <code>logs</code> directory and its files . As root:</p> 413 <pre> 414 # chgrp -R wwserver /usr/local/webwork/system/logs 415 </pre> 416 417 <p>Check that the path to the various Netpbm utilities are correct in the two 418 shell scripts <code>gif2eps</code> and <code>png2eps</code> which are located in 419 the <code>/usr/local/webwork/system/scripts/</code> directory. You may have to 420 modify <code>NETPBM</code> which is set to <code>/usr/bin</code>. Use 421 <code>which giftopnm</code>, for example, to determine the location of the 422 <code>giftopnm</code> binary.</pre> If you have trouble displaying graphs, read 423 the comment in both these shell scripts concerning the <code>-nosetpage</code> 424 switch.</p> 425 426 <p>There are some user-definable settings that you should customize in the file 427 Global.pm. This file is located at: 428 <code>/usr/local/webwork/system/lib/Global.pm</code></p> 429 <pre> 430 ################################ 431 # Local configuration settings # 432 ################################ 433 434 $legalAddress 435 A perl regular expression which email addresses must in order 436 to be considered valid. By default, this is set to accept any 437 string as a valid email address. However, you may wish to 438 set this to something less permissive. 439 $webmaster 440 The address of the WeBWorK webmaster. 441 $smtpServer 442 Your sendmail server. It should usually be set to 'localhost' 443 unless your sendmail server resides on another machine. In 444 that case, specify another server. 445 $dirDelim 446 The character which separates directories in a path name. 447 For UNIX systems this should be set to "/". 448 449 ########################### 450 # Local external programs # 451 ########################### 452 453 $externalLaTeX2HTMLPath 454 The path to LaTeX2HTML. Usually "/usr/bin/latex2html". 455 $externalLaTeX2HTMLVersion 456 The version of LaTeX2HTML installed. This controls what 457 switches are sent to the program. For version 98.1p1 or 458 later, use "98.1p1". For earlier versions, use "96.1". 459 $externalLaTeX2HTMLInit 460 The path to the LaTeX2HTML init file. You can leave this 461 as is. 462 $externalLaTeX2HTMLSupportPath 463 The directory in which LaTeX2HTML support binaries are 464 installed. This is the same directory where latex itself 465 lives. 466 $externalTTHPath 467 $externalLatexPath 468 $externalDvipsPath 469 $externalGsPath 470 These define the locations of the 'tth', 'latex', 'dvips', 471 and 'gs' programs, and are set to /usr/bin/tth, etc. by default. Use 472 `which latex', for example, to determine the location of 473 the latex binary. 474 475 ##################### 476 # Internal settings # 477 ##################### 478 479 $logAccessData 480 If you would like to log all studnet actions on your 481 system, set this to 1, otherwise leave it at 0. 482 $psvn_digits 483 This is usually safe to leave at 6, but read the comments 484 above it in Global.pm for more information. 485 $available_mode_list 486 Comment out any display modes that you do not want available to students. You can also 487 edit the external name of a mode but do not change the internal symbol. All modes 488 except HTML (which is not very useful) require additional software to be installed--- 489 see Step 2 above. 490 $htmlModeDefault 491 Set this to one of the following: 492 'HTML' for raw TeX display of equations (not recommended for a working system) 493 'HTML_tth' for formatted HTML (fast but sometimes ugly) 494 'Latex2HTML' for image equations (pretty but slow unless cached images are precreated) 495 'HTML_dpng' for image equations (same quality output as Latex2HTML and almost as fast 496 as tth but dvipng is still in a beta version) 497 </pre> 498 <p>Many other configuration settings live in Global.pm. We suggest that you read 499 through the entire file. Note that the settings in Global.pm provide system wide 500 defaults that apply to all courses. All of these settings can be changed for 501 individual courses by redefining them in the individaul course's 502 webworkCourse.ph file. After you configure Global.pm to your satisfaction, you 503 are done with the WeBWorK system setup.</p> 504 <hr> 505 <h2>Step 5: Installing the problem set template files</h2> 506 <p>Before WeBWorK can be functional, problem set template files must be present. 507 Download the templates archive from the WeBWorK web site, as you did with the 508 WeBWorK archive.</p> 509 <pre> 510 templates_VERSION_SUBVERSION-MONTH-DAY-YEAR.tar.gz 511 </pre> 512 <p>Move (or copy) the templates archive to the WeBWorK directory and untar it.</p> 513 <pre> 514 > mv templates_VERSION_SUBVERSION-MONTH-DAY-YEAR.tar.gz /usr/local/webwork 515 > tar -xzf templates_VERSION_SUBVERSION-MONTH-DAY-YEAR.tar.gz 516 > mv templates_VERSION_SUBVERSION-MONTH-DAY-YEAR/templates . 517 > rmdir templates_VERSION_SUBVERSION-MONTH-DAY-YEAR 518 > rm templates_VERSION_SUBVERSION-MONTH-DAY-YEAR.tar.gz 519 </pre> 520 <p>Set the permissions on the new directory.</p> 521 <pre> 522 > chgrp -R wwadmin templates 523 > chmod -R 775 templates 524 </pre> 525 <p>The problem set templates are not accessed directly from this location. They 526 are instead copied into each course which is created. This allows professors to 527 modify their local copies without disturbing other courses.</p> 528 <p>Now would be a good time to add the scripts directory to your search path, so 529 that you don't have to type the full path of the command each time. If you are 530 using bash, add this line to the bottom of the .bash_profile file in your home 531 directory:</p> 532 <pre> 533 PATH = "/usr/local/webwork/system/scripts:${PATH}" 534 </pre> 535 <p>Log out and log back in again to add the new path. Depending on your setup, 536 you will probably have to out of and back into X windows for changes to take 537 effect. Type <code>echo $PATH</code> to check that the path has been set 538 properly.</p> 539 <hr> 540 <h2>Step 6: Creating a course</h2> 541 <p>To test your installation of WeBWorK, you must now create a course. The base 542 you will use to create this course is located in 543 <code>/usr/local/webwork/courses/blankCourse</code>. The course we are going to 544 create now will be called <code>demoCourse</code>.</p> 545 <p>Each course has a UNIX user group associated with it. The group should 546 contain any users who should be able to view or edit the course files directly 547 (such as the professor and any teaching assistants), and the system user under 548 which the web server runs, <code>wwserver</code>. The convention on Rochester's 549 installation of WeBWorK is to name each group after the course it represents, 550 only using capital letters. However, some Linux distributions disallow uppercase 551 group names. Use your own judgement.</p> 552 <p>As root, create a group for demoCourse and add yourself and the web server to 553 it. Since we're adding the web server to a new group, we have to restart it:</p> 554 <pre> 555 # groupadd DEMOCOURSE 556 # usermod -G DEMOCOURSE,<othergroups> wwserver 557 # usermod -G DEMOCOURSE,<othergroups> <username> 558 # apachectl restart 559 </pre> 560 <p>Now, log out of your normal user account and log back in so that your group 561 membership will be recognized.</p> 562 <p>Next, you will need to make a copy of <code>blankCourse</code> called 563 <code>demoCourse</code> and add some problem set templates to it. As a normal 564 user:</p> 565 <pre> 566 > cd /usr/local/webwork/courses 567 > cp -R blankCourse demoCourse 568 > cd demoCourse/templates 569 > cp -R /usr/local/webwork/templates/set0 . 570 > cp /usr/local/webwork/templates/set0.def . 571 </pre> 572 <p>Repeat the last two commands for any other sets you wish to import into the 573 demo course. A popular option is to import <em>all</em> of the sets. To do this, 574 type:</p> 575 <pre> 576 > cp -R /usr/local/webwork/templates/set* . 577 </pre> 578 <p>WeBWorK comes with a script which completes the setup of a new course. We'll 579 run it now, as a normal user:</p> 580 <pre> 581 > cd /usr/local/webwork/courses/demoCourse 582 > course_webwork_setup.pl 583 </pre> 584 <p>This script will ask you several questions about the environment in which the 585 course will be used. Read the information given with each choice carefully. 586 Recommended choices are as follows:</p> 587 <pre> 588 Q: Do you wish to setup a "working" or a "demo" version? (w or d) 589 A: w 590 Q: Do you want to create missing directories (if any)? (y or n) 591 A: y 592 Q: ENTER course URL 593 A: press ENTER to accept the default /webwork/demoCourse 594 Q: ENTER cgi WeBWorK URL 595 A: press ENTER to accept the default /cgi-bin/webwork/system 596 Q: ENTER course link (i.e. classID) name 597 A: press ENTER to accept the default demoCourse 598 Q: ENTER group name 599 A: DEMOCOURSE 600 Q: Do you want to create a new webworkCourse.ph...? 601 A: y 602 Q: Do you want to create a new index.html...? 603 A: y 604 Q: Do you want to set the group for all directories and files? 605 A: y 606 Q: Do you want to set default "working" permissions for all directories 607 and files? 608 A: y 609 </pre> 610 <p>We'll now make the template directory setgid so that new problems and problem 611 sets will get the correct group and permissions.</p> 612 <pre> 613 > chmod g+s templates 614 </pre> 615 <p>To let the WeBWorK system know that it has a new course, add a symlink to 616 demoCourse in the <code>system/courses</code> directory. If you do not do this, 617 the WeBWorK system will not be able to access the course — this is a good 618 way to "turn off" a course.</p> 619 <pre> 620 > ln -s /usr/local/webwork/courses/demoCourse /usr/local/webwork/system/courses/ 621 </pre> 622 <p>Each course has a "visible" interface in the webwork directory on the web 623 server's document root. This allows the course home page to be accessed via 624 <code>http://servername/webwork/courseName/</code> rather than having to call 625 the login script directly. As a normal user, create this link:</p> 626 <pre> 627 > ln -s /usr/local/webwork/courses/demoCourse/html $DOCUMENT_ROOT/webwork/demoCourse 628 </pre> 629 <p>Now, we're going to run some scripts to finish setting up the course. As a 630 normal user:</p> 631 <pre> 632 > cd /usr/local/webwork/courses/demoCourse/templates 633 > import_classlist-database.pl demoCourse defaultClasslist.lst 634 > setProfPermissions.pl demoCourse professor 635 </pre> 636 <p>There. You've finished the demoCourse setup. The process for setting up 637 additional courses is identical to this. To verify that you've set everything up 638 properly, view the following URL in your browser: 639 <code>http://your.server.name/webwork/demoCourse/</code></p> 640 <p>Note that the "trailing slash" is required unless redirects work on your server.</p> 641 <p>You should see your newly-generated course index page. If this works, click 642 the Login button and enter the following information:</p> 643 <pre> 644 login: professor 645 password: 111-11-1111 646 </pre> 647 <p>Even though this is only the demo course, it's a good idea to change your 648 password to prevent unauthorized access.</p> 649 <p>You should be logged in as the professor. This means you will see a 650 link for Click Enter Professor's Page. Click on it. </p> 651 652 <p>Before you do anything, you have to build some sets. This will test to make 653 sure that all of the problem rendering methods work. First, click <strong>Enter 654 Build Problem Set Page</strong> which should be the only option you see. Then, 655 select one or more problem sets from the list and click <strong>Build Problem 656 Set(s)</strong>. WeBWorK will report that the problem sets have been built. At 657 the bottom of the resulting page, click <strong>Problem Sets</strong>.</p> 658 <p>Now that the sets have been built, you can test various methods of displaying 659 them. Note that the first few times you display problems the system may take an 660 unusually long time since it may have to run Metafont to create LaTeX fonts. 661 Select a set, select <strong>PDF form</strong> and click 662 <strong>Get_hard_copy</strong>. After a moment, WeBWorK will send you a PDF 663 file. Acrobat may open automatically, or you may have to wrestle with your 664 browser a bit to see it.</p> 665 <p>Next, we can check onscreen display. Select a problem set and click 666 <strong>Do_problem_set</strong>. View several problems from the set on all three 667 display modes: <strong>text</strong>, raw TeX source code, <strong>formatted- 668 text</strong>, TTH output, and <strong>typeset</strong>, LaTeX2HTML output. 669 Typeset mode takes quite some time on the first view of any problem as it has to 670 generate images for the equations. However, subsequent views take advantage of 671 cached temp files.</p> 672 <p>Return to the Professor's Page and now you will see a large number of utilities 673 which you can use in administering a weBWorK course. 674 <hr> 675 <h2>Step 7: Customizing the course set up</h2> 676 <p>This is unecessary for the demoCourse but is something that should be done for 677 regular courses. Edit the file 678 <code>/usr/local/webwork/courses/demoCourse/webworkCourse.ph</code> entering the correct data. 679 At the very least you should enter data for 680 <pre> 681 $Global::feedbackAddress 682 $smtpSender 683 $PG_environment{'PRINT_FILE_NAMES_FOR'} 684 </pre> 685 In general you should look through <code>Global.pm</code> (located in 686 <code>/usr/local/webwork/system/lib/</code>) and <code>webworkCourse.ph</code> (located in 687 <code>/usr/local/webwork/courses/course_name/</code>). The variables defined in 688 <code>Global.pm</code> set defaults and 689 parameters for the whole WeBWorK system. The variables defined in 690 <code>webworkCourse.ph</code> set defaults and 691 parameters for an individual course. The defaults given in <code>Global.pm</code> can 692 be over ridden for an individual course by redefining 693 them in <code>webworkCourse.ph</code>. 694 695 696 </p> 697 <hr> 698 <h2>Step 8: Separating Static and Variable WeBWorK data</h2> 699 <p>Right now, all WeBWorK files are located under <code>/usr/local</code>. While 700 this is the simplest setup, it is not the best way to do things. The WeBWorK 701 "system" is fine under <code>/usr/local</code> as it is static data which is not 702 going to change during the life of the system, does not need to be backed up 703 frequently, and can be located on a read-only storage medium (after initial 704 configuration, of course). However, the "courses" data should really be located 705 under <code>/var/local</code>, as it is variable data and should be on storage 706 that is mounted read-write and is backed up regularly. If you want to set up 707 WeBWorK this way, follow the instructions below.</p> 708 <p>As root, create a <code>webwork</code> directory in <code>/var/local</code> 709 and set privileges on it:</p> 710 <pre> 711 # mkdir /var/local/webwork 712 # chown <username> /var/local/webwork 713 # chgrp wwadmin /var/local/webwork 714 </pre> 715 <p>As a regular user, move the courses directory into your new 716 <code>webwork</code> directory:</p> 717 <pre> 718 > mv /usr/local/webwork/courses /var/local/webwork 719 </pre> 720 <p>Now, a slight modification to the structure of the WeBWorK system structure 721 must be made. The directory <code>/usr/local/webwork/system/courses</code> 722 contains symlinks to each course directory, for use by system scripts. These 723 symlinks must be created manually for each course. Instead of this, we would 724 like this directory to point to the actual courses directory. Therefore, as a 725 normal user, run:</p> 726 <pre> 727 > rm -r /usr/local/webwork/system/courses 728 > ln -s /var/local/webwork/courses /usr/local/webwork/system 729 </pre> 730 <p>Also, it is a good idea to "crosslink" the courses and system directory so 731 that we can easily move between them without typing out the absolute paths:</p> 732 <pre> 733 > ln -s /var/local/webwork/courses /usr/local/webwork 734 > ln -s /usr/local/webwork/system /var/local/webwork 735 </pre> 736 <p>Some WeBWorK documentation will instruct you to maintain course symlinks in 737 <code>/usr/local/webwork/system/courses</code>. After you make these 738 modifications, you no longer need to do this.</p> 739 <hr> 740 <h2>Step 9: Separating out temporary WeBWorK data</h2> 741 <p>This is an advanced step that major users may want to consider.</p> 742 <p>If you are using WeBWorK with a substantial number of students (say a hundred 743 or more) you probably should use the following method of setting up tmp 744 directories. This is what we do at Rochester. The main point is that WeBWorK 745 creates a lot of small temporary (and not so temporary) files and these can use 746 up a lot of inodes (i.e. disk resources) and also slow up backups. </p> 747 748 <p>As an aside --- this is not a system setup issue--- every week or two it's a 749 good idea to go to the prof page, then Housekeeping utilities (item 14), and 750 click on remove tmp files and compress the gdbm database. This removes all non 751 latex2html tmp files. It will also substancially reduce the size of the webwork 752 database.</p> 753 754 <p>In a standard setup under the html directory for a course you will find a tmp 755 directory. Under that are various directories. Everything under tmp will be 756 recreated if deleted. Since latex2html (l2h), which is used for typeset output, 757 is so slow, we cache the l2h images and these are saved under html/tmp/l2h/ . 758 These l2h files should be kept at least until students no longer are looking at 759 the problems (we keep them all semester). If you remove them, it slows things 760 down since these images have to be recreated. The remove tmp files button 761 referred to above does not delete these files but does delete all other tmp 762 files.</p> 763 764 <p>Where the tmp directory for a course is located is determined by the 765 webworkCourse.ph file. What we do at Rochester is create a new file system for 766 all tmp directories from all courses and put it under the <code>$DOCUMENT_ROOT</code> directory. 767 So we have</p> 768 769 <code>$DOCUMENT_ROOT/tmp/</code> 770 771 <p>the tmp directory (file system) is set up with (this is system dependent)</p> 772 773 <code>newfs -i 512 tmp</code> 774 775 <p>so there are plenty of inodes (the -i switch specifies number of bytes per 776 inode). Also this file system is never backed up. I think by default most OS's, 777 e.g. Solaris, use many fewer inodes. </p> 778 779 <p>Under tmp we have a directory for each course, e.g. 780 781 <code>$DOCUMENT_ROOT/tmp/mth142/</code></p> 782 783 <p>We change the webworkCourse.ph file for each course as follows: </p> 784 785 <p>FIRST CHANGE</p> 786 <pre> 787 # This is the temp directory used by downloadPS, etc 788 789 #$courseTempDirectory = "${classDirectory}html/tmp/"; 790 $courseTempDirectory = "$DOCUMENT_ROOT/tmp/mth142/"; 791 </pre> 792 <p>SECOND CHANGE</p> 793 <pre> 794 # This is the URL of the course tmp directory. This is for temporary storage of 795 # html files, images, etc that have to accessible to the webserver. This directory 796 # contains the subdirectories l2h, gif, eps, and html (not the ${classDirectory}html 797 # directory). All these subdirectories and their files will be recreated if deleted 798 # (althought recreating l2h files is time consuminmg). The location of this directory 799 # may be changed fast disk which is not backed up. 800 801 #$courseTempURL = "${htmlURL}tmp/"; 802 $courseTempURL = "/tmp/mth142/"; 803 </pre> 804 805 <p>Note that if you do not set up the <code>tmp</code> as a subdirectory of $DOCUMENT_ROOT/ 806 you will have to setup a link in the $DOCUMENT_ROOT/ pointing to the <code>tmp</code> directory. 807 If you name the link <code>tmp</code>, you can use <code>$courseTempURL</code> as above.</p> 808 809 <p>Also you should note that the access and timing logs can get huge. These are 810 in <code>webwork/system/logs/</code></p> 811 812 <p>By default, these logs are not kept. You can turn on the access log by 813 changing $logAccessData = 0; in the Global.pm . The timing log keeps track of 814 how fast the server is responding. You can keep track of individual scripts. The 815 most important one is processProblem8.pl (edit around line 40 $main::logTimingData = 816 1;). </p> 817 <hr> 818 <h2>Step 10: Obtaining Additional Support</h2> 819 <p>Online support is available at: <a 820 href="http://webwork.math.rochester.edu/docs/">http://webwork.math.rochester.edu 821 /docs/</a></p> 822 </body> 823 </html>
| aubreyja at gmail dot com | ViewVC Help |
| Powered by ViewVC 1.0.9 |