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