Parent Directory
| 
Revision Log
very minor change
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 an 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 or 1.29. 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 $externalTTHPath 454 $externalDvipngPath 455 $externalLaTeX2HTMLPath 456 $externalLatexPath 457 $externalDvipsPath 458 $externalGsPath 459 These define the locations of the 'tth', 'dvipng', 'latex2html', 460 'latex', 'dvips', and 'gs' programs, and are set to /usr/bin/tth, 461 etc. by default. Use `which latex', for example, to determine the 462 location of the latex binary. 463 464 $dvipngMode, $dvipngDPI, $dvipngScaling, and $dvipngShrinkFactor 465 These control the fonts produced by dvipng. Other than possibly trying 466 ljfivemp, you probably should not change these unless you know what you 467 are doing. 468 469 $externalLaTeX2HTMLVersion 470 The version of LaTeX2HTML installed. This controls what 471 switches are sent to the program. For version 98.1p1 or 472 later, use "98.1p1". For earlier versions, use "96.1". 473 $externalLaTeX2HTMLInit 474 The path to the LaTeX2HTML init file. You can leave this 475 as is. 476 477 $extendedPath 478 The path to support binaries required by LaTeX, etc. The given path 479 ':/usr/bin:/usr/local/bin' should work in most cases. 480 481 ##################### 482 # Display Modes # 483 ##################### 484 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. This is our recommended choice.) 497 498 ##################### 499 # Internal settings # 500 ##################### 501 502 $logAccessData 503 If you would like to log all studnet actions on your 504 system, set this to 1, otherwise leave it at 0. 505 $psvn_digits 506 This is usually safe to leave at 6, but read the comments 507 above it in Global.pm for more information. 508 </pre> 509 <p>Many other configuration settings live in Global.pm. We suggest that you read 510 through the entire file. Note that the settings in Global.pm provide system wide 511 defaults that apply to all courses. All of these settings can be changed for 512 individual courses by redefining them in the individaul course's 513 webworkCourse.ph file. After you configure Global.pm to your satisfaction, you 514 are done with the WeBWorK system setup.</p> 515 <hr> 516 <h2>Step 5: Installing the problem set template files</h2> 517 <p>Before WeBWorK can be functional, problem set template files must be present. 518 Download the templates archive from the WeBWorK web site, as you did with the 519 WeBWorK archive.</p> 520 <pre> 521 templates_VERSION_SUBVERSION-MONTH-DAY-YEAR.tar.gz 522 </pre> 523 <p>Move (or copy) the templates archive to the WeBWorK directory and untar it.</p> 524 <pre> 525 > mv templates_VERSION_SUBVERSION-MONTH-DAY-YEAR.tar.gz /usr/local/webwork 526 > tar -xzf templates_VERSION_SUBVERSION-MONTH-DAY-YEAR.tar.gz 527 > mv templates_VERSION_SUBVERSION-MONTH-DAY-YEAR/templates . 528 > rmdir templates_VERSION_SUBVERSION-MONTH-DAY-YEAR 529 > rm templates_VERSION_SUBVERSION-MONTH-DAY-YEAR.tar.gz 530 </pre> 531 <p>Set the permissions on the new directory.</p> 532 <pre> 533 > chgrp -R wwadmin templates 534 > chmod -R 775 templates 535 </pre> 536 <p>The problem set templates are not accessed directly from this location. They 537 are instead copied into each course which is created. This allows professors to 538 modify their local copies without disturbing other courses.</p> 539 <p>Now would be a good time to add the scripts directory to your search path, so 540 that you don't have to type the full path of the command each time. If you are 541 using bash, add this line to the bottom of the .bash_profile file in your home 542 directory:</p> 543 <pre> 544 PATH = "/usr/local/webwork/system/scripts:${PATH}" 545 </pre> 546 <p>Log out and log back in again to add the new path. Depending on your setup, 547 you will probably have to out of and back into X windows for changes to take 548 effect. Type <code>echo $PATH</code> to check that the path has been set 549 properly.</p> 550 <hr> 551 <h2>Step 6: Creating a course</h2> 552 <p>To test your installation of WeBWorK, you must now create a course. The base 553 you will use to create this course is located in 554 <code>/usr/local/webwork/courses/blankCourse</code>. The course we are going to 555 create now will be called <code>demoCourse</code>.</p> 556 <p>Each course has a UNIX user group associated with it. The group should 557 contain any users who should be able to view or edit the course files directly 558 (such as the professor and any teaching assistants), and the system user under 559 which the web server runs, <code>wwserver</code>. The convention on Rochester's 560 installation of WeBWorK is to name each group after the course it represents, 561 only using capital letters. However, some Linux distributions disallow uppercase 562 group names. Use your own judgement.</p> 563 <p>As root, create a group for demoCourse and add yourself and the web server to 564 it. Since we're adding the web server to a new group, we have to restart it:</p> 565 <pre> 566 # groupadd DEMOCOURSE 567 # usermod -G DEMOCOURSE,<othergroups> wwserver 568 # usermod -G DEMOCOURSE,<othergroups> <username> 569 # apachectl restart 570 </pre> 571 <p>Now, log out of your normal user account and log back in so that your group 572 membership will be recognized.</p> 573 <p>Next, you will need to make a copy of <code>blankCourse</code> called 574 <code>demoCourse</code> and add some problem set templates to it. As a normal 575 user:</p> 576 <pre> 577 > cd /usr/local/webwork/courses 578 > cp -R blankCourse demoCourse 579 > cd demoCourse/templates 580 > cp -R /usr/local/webwork/templates/set0 . 581 > cp /usr/local/webwork/templates/set0.def . 582 </pre> 583 <p>Repeat the last two commands for any other sets you wish to import into the 584 demo course. A popular option is to import <em>all</em> of the sets. To do this, 585 type:</p> 586 <pre> 587 > cp -R /usr/local/webwork/templates/set* . 588 </pre> 589 <p>WeBWorK comes with a script which completes the setup of a new course. We'll 590 run it now, as a normal user:</p> 591 <pre> 592 > cd /usr/local/webwork/courses/demoCourse 593 > course_webwork_setup.pl 594 </pre> 595 <p>This script will ask you several questions about the environment in which the 596 course will be used. Read the information given with each choice carefully. 597 Recommended choices are as follows:</p> 598 <pre> 599 Q: Do you wish to setup a "working" or a "demo" version? (w or d) 600 A: w 601 Q: Do you want to create missing directories (if any)? (y or n) 602 A: y 603 Q: ENTER course URL 604 A: press ENTER to accept the default /webwork/demoCourse 605 Q: ENTER cgi WeBWorK URL 606 A: press ENTER to accept the default /cgi-bin/webwork/system 607 Q: ENTER course link (i.e. classID) name 608 A: press ENTER to accept the default demoCourse 609 Q: ENTER group name 610 A: DEMOCOURSE 611 Q: Do you want to create a new webworkCourse.ph...? 612 A: y 613 Q: Do you want to create a new index.html...? 614 A: y 615 Q: Do you want to set the group for all directories and files? 616 A: y 617 Q: Do you want to set default "working" permissions for all directories 618 and files? 619 A: y 620 </pre> 621 <p>We'll now make the template directory setgid so that new problems and problem 622 sets will get the correct group and permissions.</p> 623 <pre> 624 > chmod g+s templates 625 </pre> 626 <p>To let the WeBWorK system know that it has a new course, add a symlink to 627 demoCourse in the <code>system/courses</code> directory. If you do not do this, 628 the WeBWorK system will not be able to access the course — this is a good 629 way to "turn off" a course.</p> 630 <pre> 631 > ln -s /usr/local/webwork/courses/demoCourse /usr/local/webwork/system/courses/ 632 </pre> 633 <p>Each course has a "visible" interface in the webwork directory on the web 634 server's document root. This allows the course home page to be accessed via 635 <code>http://servername/webwork/courseName/</code> rather than having to call 636 the login script directly. As a normal user, create this link:</p> 637 <pre> 638 > ln -s /usr/local/webwork/courses/demoCourse/html $DOCUMENT_ROOT/webwork/demoCourse 639 </pre> 640 <p>Now, we're going to run some scripts to finish setting up the course. As a 641 normal user:</p> 642 <pre> 643 > cd /usr/local/webwork/courses/demoCourse/templates 644 > import_classlist-database.pl demoCourse defaultClasslist.lst 645 > setProfPermissions.pl demoCourse professor 646 </pre> 647 <p>There. You've finished the demoCourse setup. The process for setting up 648 additional courses is identical to this. To verify that you've set everything up 649 properly, view the following URL in your browser: 650 <code>http://your.server.name/webwork/demoCourse/</code></p> 651 <p>Note that the "trailing slash" is required unless redirects work on your server.</p> 652 <p>You should see your newly-generated course index page. If this works, click 653 the Login button and enter the following information:</p> 654 <pre> 655 login: professor 656 password: 111-11-1111 657 </pre> 658 <p>Even though this is only the demo course, it's a good idea to change your 659 password to prevent unauthorized access.</p> 660 <p>You should be logged in as the professor. This means you will see a 661 link for Click Enter Professor's Page. Click on it. </p> 662 663 <p>Before you do anything, you have to build some sets. This will test to make 664 sure that all of the problem rendering methods work. First, click <strong>Enter 665 Build Problem Set Page</strong> which should be the only option you see. Then, 666 select one or more problem sets from the list and click <strong>Build Problem 667 Set(s)</strong>. WeBWorK will report that the problem sets have been built. At 668 the bottom of the resulting page, click <strong>Problem Sets</strong>.</p> 669 <p>Now that the sets have been built, you can test various methods of displaying 670 them. Note that the first few times you display problems the system may take an 671 unusually long time since it may have to run Metafont to create LaTeX fonts. 672 Select a set, select <strong>PDF form</strong> and click 673 <strong>Get_hard_copy</strong>. After a moment, WeBWorK will send you a PDF 674 file. Acrobat may open automatically, or you may have to wrestle with your 675 browser a bit to see it.</p> 676 <p>Next, we can check onscreen display. Select a problem set and click 677 <strong>Do_problem_set</strong>. View several problems from the set on all four 678 display modes: <strong>text</strong>, raw TeX source code, <strong>formatted- 679 text</strong>, TTH output, <strong>typeset2</strong>, dvipng output 680 and <strong>typeset</strong>, LaTeX2HTML output. 681 Typeset mode takes quite some time on the first view of any problem as it has to 682 generate images for the equations. However, subsequent views take advantage of 683 cached temp files.</p> 684 <p>Return to the Professor's Page and now you will see a large number of utilities 685 which you can use in administering a weBWorK course. 686 <hr> 687 <h2>Step 7: Customizing the course set up</h2> 688 <p>This is unecessary for the demoCourse but is something that should be done for 689 regular courses. Edit the file 690 <code>/usr/local/webwork/courses/demoCourse/webworkCourse.ph</code> entering the correct data. 691 At the very least you should enter data for 692 <pre> 693 $Global::feedbackAddress 694 $smtpSender 695 $PG_environment{'PRINT_FILE_NAMES_FOR'} 696 </pre> 697 In general you should look through <code>Global.pm</code> (located in 698 <code>/usr/local/webwork/system/lib/</code>) and <code>webworkCourse.ph</code> (located in 699 <code>/usr/local/webwork/courses/course_name/</code>). The variables defined in 700 <code>Global.pm</code> set defaults and 701 parameters for the whole WeBWorK system. The variables defined in 702 <code>webworkCourse.ph</code> set defaults and 703 parameters for an individual course. The defaults given in <code>Global.pm</code> can 704 be over ridden for an individual course by redefining 705 them in <code>webworkCourse.ph</code>. 706 707 708 </p> 709 <hr> 710 <h2>Step 8: Separating Static and Variable WeBWorK data</h2> 711 <p>Right now, all WeBWorK files are located under <code>/usr/local</code>. While 712 this is the simplest setup, it is not the best way to do things. The WeBWorK 713 "system" is fine under <code>/usr/local</code> as it is static data which is not 714 going to change during the life of the system, does not need to be backed up 715 frequently, and can be located on a read-only storage medium (after initial 716 configuration, of course). However, the "courses" data should really be located 717 under <code>/var/local</code>, as it is variable data and should be on storage 718 that is mounted read-write and is backed up regularly. If you want to set up 719 WeBWorK this way, follow the instructions below.</p> 720 <p>As root, create a <code>webwork</code> directory in <code>/var/local</code> 721 and set privileges on it:</p> 722 <pre> 723 # mkdir /var/local/webwork 724 # chown <username> /var/local/webwork 725 # chgrp wwadmin /var/local/webwork 726 </pre> 727 <p>As a regular user, move the courses directory into your new 728 <code>webwork</code> directory:</p> 729 <pre> 730 > mv /usr/local/webwork/courses /var/local/webwork 731 </pre> 732 <p>Now, a slight modification to the structure of the WeBWorK system structure 733 must be made. The directory <code>/usr/local/webwork/system/courses</code> 734 contains symlinks to each course directory, for use by system scripts. These 735 symlinks must be created manually for each course. Instead of this, we would 736 like this directory to point to the actual courses directory. Therefore, as a 737 normal user, run:</p> 738 <pre> 739 > rm -r /usr/local/webwork/system/courses 740 > ln -s /var/local/webwork/courses /usr/local/webwork/system 741 </pre> 742 <p>Also, it is a good idea to "crosslink" the courses and system directory so 743 that we can easily move between them without typing out the absolute paths:</p> 744 <pre> 745 > ln -s /var/local/webwork/courses /usr/local/webwork 746 > ln -s /usr/local/webwork/system /var/local/webwork 747 </pre> 748 <p>Some WeBWorK documentation will instruct you to maintain course symlinks in 749 <code>/usr/local/webwork/system/courses</code>. After you make these 750 modifications, you no longer need to do this.</p> 751 <hr> 752 <h2>Step 9: Separating out temporary WeBWorK data</h2> 753 <p>This is an advanced step that major users may want to consider.</p> 754 <p>If you are using WeBWorK with a substantial number of students (say a hundred 755 or more) you probably should use the following method of setting up tmp 756 directories. This is what we do at Rochester. The main point is that WeBWorK 757 creates a lot of small temporary (and not so temporary) files and these can use 758 up a lot of inodes (i.e. disk resources) and also slow up backups. </p> 759 760 <p>As an aside --- this is not a system setup issue--- every week or two it's a 761 good idea to go to the prof page, then Housekeeping utilities (item 14), and 762 click on remove tmp files and compress the gdbm database. This removes all non 763 latex2html tmp files. It will also substancially reduce the size of the webwork 764 database.</p> 765 766 <p>In a standard setup under the html directory for a course you will find a tmp 767 directory. Under that are various directories. Everything under tmp will be 768 recreated if deleted. Since latex2html (l2h), which is used for typeset output, 769 is so slow, we cache the l2h images and these are saved under html/tmp/l2h/ . 770 These l2h files should be kept at least until students no longer are looking at 771 the problems (we keep them all semester). If you remove them, it slows things 772 down since these images have to be recreated. The remove tmp files button 773 referred to above does not delete these files but does delete all other tmp 774 files.</p> 775 776 <p>Where the tmp directory for a course is located is determined by the 777 webworkCourse.ph file. What we do at Rochester is create a new file system for 778 all tmp directories from all courses and put it under the <code>$DOCUMENT_ROOT</code> directory. 779 So we have</p> 780 781 <code>$DOCUMENT_ROOT/tmp/</code> 782 783 <p>the tmp directory (file system) is set up with (this is system dependent)</p> 784 785 <code>newfs -i 512 tmp</code> 786 787 <p>so there are plenty of inodes (the -i switch specifies number of bytes per 788 inode). Also this file system is never backed up. I think by default most OS's, 789 e.g. Solaris, use many fewer inodes. </p> 790 791 <p>Under tmp we have a directory for each course, e.g. 792 793 <code>$DOCUMENT_ROOT/tmp/mth142/</code></p> 794 795 <p>We change the webworkCourse.ph file for each course as follows: </p> 796 797 <p>FIRST CHANGE</p> 798 <pre> 799 # This is the temp directory used by downloadPS, etc 800 801 #$courseTempDirectory = "${classDirectory}html/tmp/"; 802 $courseTempDirectory = "$DOCUMENT_ROOT/tmp/mth142/"; 803 </pre> 804 <p>SECOND CHANGE</p> 805 <pre> 806 # This is the URL of the course tmp directory. This is for temporary storage of 807 # html files, images, etc that have to accessible to the webserver. This directory 808 # contains the subdirectories l2h, gif, eps, and html (not the ${classDirectory}html 809 # directory). All these subdirectories and their files will be recreated if deleted 810 # (althought recreating l2h files is time consuminmg). The location of this directory 811 # may be changed fast disk which is not backed up. 812 813 #$courseTempURL = "${htmlURL}tmp/"; 814 $courseTempURL = "/tmp/mth142/"; 815 </pre> 816 817 <p>Note that if you do not set up the <code>tmp</code> as a subdirectory of $DOCUMENT_ROOT/ 818 you will have to setup a link in the $DOCUMENT_ROOT/ pointing to the <code>tmp</code> directory. 819 If you name the link <code>tmp</code>, you can use <code>$courseTempURL</code> as above.</p> 820 821 <p>Also you should note that the access and timing logs can get huge. These are 822 in <code>webwork/system/logs/</code></p> 823 824 <p>By default, these logs are not kept. You can turn on the access log by 825 changing $logAccessData = 0; in the Global.pm . The timing log keeps track of 826 how fast the server is responding. You can keep track of individual scripts. The 827 most important one is processProblem8.pl (edit around line 40 $main::logTimingData = 828 1;). </p> 829 <hr> 830 <h2>Step 10: Obtaining Additional Support</h2> 831 <p>Online support is available at: <a 832 href="http://webwork.math.rochester.edu/docs/">http://webwork.math.rochester.edu 833 /docs/</a></p> 834 </body> 835 </html>
| aubreyja at gmail dot com | ViewVC Help |
| Powered by ViewVC 1.0.9 |