Parent Directory
| 
Revision Log
changed copyright dates to 2000-2004
1 2 WeBWorK 3 Online Homework Delivery System 4 Version 2.0 5 6 Copyright 2000-2004, The WeBWorK Project 7 All rights reserved. 8 9 The contents of this file were pulled from the WeBWorK wiki on 04-January-2004. 10 The latest version is availabe at http://devel.webwork.rochester.edu/. In this 11 document: 12 13 DESCRIPTION 14 SYSTEM REQUIREMENTS 15 INSTALLATION 16 APACHE CONFIGURATION 17 WEBWORK CONFIGURATION 18 COURSE CREATION 19 20 ____DESCRIPTION_________________________________________________________________ 21 22 WeBWorK is a Perl-based system for delivering individualized homework 23 problems over the web. By providing students with immediate feedback as to 24 the correctness of their answers, students are encouraged to make multiple 25 attempts until they succeed. By individualizing problems, cheating is 26 discouraged. By providing instructors with real-time statistics, lesson 27 plans can be customized to better serve students. 28 29 ____SYSTEM REQUIREMENTS_________________________________________________________ 30 31 Here are the software packages required by WeBWorK 2. Most OS vendors 32 precompiled binaries of these packages. The version requirements given 33 below are somewhat imprecise. 34 35 +-----------------------------------------------------------------------------------+ 36 | Package | Required For | Source |Version| 37 |-----------+----------------+----------------------------------------------+-------| 38 |Perl |basic operation |http://perl.org/ |>= 5.6 | 39 |-----------+----------------+----------------------------------------------+-------| 40 |Apache |basic operation |http://httpd.apache.org/ |1.3.x | 41 |-----------+----------------+----------------------------------------------+-------| 42 |mod_perl |basic operation |http://perl.apache.org/ |1.x | 43 |-----------+----------------+----------------------------------------------+-------| 44 |LaTeX |basic operation |http://www.tug.org/tetex/ | | 45 |-----------+----------------+----------------------------------------------| | 46 |netpbm |basic operation |http://netpbm.sf.net/ | | 47 |-----------+----------------+----------------------------------------------+-------| 48 |dvipng |"images" display|http://sourceforge.net/projects/preview-latex/|>= 0.8 | 49 | |mode | | | 50 |-----------+----------------+----------------------------------------------+-------| 51 |preview.sty|"images" display|http://sourceforge.net/projects/preview-latex/| | 52 | |mode | | | 53 |-----------+----------------+----------------------------------------------| | 54 |tth |"formatted-text"|http://hutchinson.belmont.ma.us/tth/ | | 55 | |display mode | | | 56 |-----------+----------------+----------------------------------------------| | 57 |libgdbm |GDBM database |http://www.gnu.org/software/gdbm/gdbm.html | | 58 | |backend | | | 59 +-----------------------------------------------------------------------------------+ 60 61 Perl must be compiled with GDBM support to use GDBM databases. (WeBWorK 62 1.x databases are usually GDBM.) Most OS vendors compile their perl 63 packages with this option on. 64 65 Also, some perl modules are required. All are available in CPAN, and many 66 OS vendors provide packages of these modules. 67 68 * For WeBWorK 2 69 70 * Bundle::Apache 71 * DBI and the DBD:: module of your choice (required if you wish to 72 use an SQL database backend) 73 * Data::UUID 74 * Date::Format and Date::Parse 75 * Mail::Sender 76 * SOAP::Lite (required if you wish to use a remote renderer) 77 78 * For PG (required if you wish to use a local renderer) 79 80 * GD 81 82 ____INSTALLATION________________________________________________________________ 83 84 Unpacking from CVS 85 86 A WeBWorK installation currently consists of two directory trees, a 87 webwork tree and a pg tree. These trees are stored as the CVS modules 88 webwork-modperl and pg, respectively. To check out from CVS, follow the 89 instructions in the WeBWorKCVS topic. After installing the SSH key, check 90 out the webwork-modperl and pg modules: 91 92 $ cvs checkout -P webwork-modperl 93 $ cvs checkout -P pg 94 95 Unpacking from tarballs 96 97 First, download the two tarballs: webwork-X.X.tar.bz2 and pg-X.X.tar.bz2. 98 ("X.X" represents the version number, i.e. "2.0pr2".) These files are 99 available from our SourceForge project page: 100 http://sourceforge.net/project/showfiles.php?group_id=93112 101 102 Untar them somewhere (like your home directory). 103 104 $ tar -xjf webwork-2.0pr2.tar.bz2 105 $ tar -xjf pg-2.0pr2.tar.bz2 106 107 Then, become root and move the directories to the your installation 108 directory. I prefer to use /opt. 109 110 # cp -r webwork-2.0pr2 /opt 111 # cp -r pg-2.0pr2 /opt 112 113 System permissions 114 115 Some directories must be writeable by the web server: 116 117 +---------------------------+ 118 | directory | 119 |---------------------------| 120 |webwork-2.0pr2/DATA | 121 |---------------------------| 122 |webwork-2.0pr2/DATA/uploads| 123 |---------------------------| 124 |webwork-2.0pr2/htdocs/tmp | 125 +---------------------------+ 126 127 Assuming that your web server runs as the user www, you can achieve this 128 by running: 129 130 # chown www webwork-2.0pr2/DATA 131 # chown www webwork-2.0pr2/DATA/uploads 132 # chwon www webwork-2.0pr2/htdocs/tmp 133 134 ____APACHE CONFIGURATION________________________________________________________ 135 136 WeBWorK requires Apache 1.3 and mod_perl 1.0 to run. For instructions on 137 how to compile, install, and test mod_perl, consult the mod_perl 138 Installation Guide. 139 140 Once Apache and mod_perl are installed, Apache must be configured to 141 handle requests for WeBWorK. Apache needs to know about three locations: 142 143 * The location that is handled by the Apache::WeBWorK module, usually 144 /webwork2. 145 * The location of system-wide resources, usually /webwork2_files. 146 * The location of course-specific resources, usually /webwork2_courses. 147 148 In the following examples, I'm assuming that you unpacked the WeBWorK 2 149 distribution to /opt/webwork2, and the PG distribution to /opt/pg. If your 150 Apache configuration is sufficiently paranoid, you may need to add the 151 following to the Location and Directory stanzas below, to permit access: 152 153 Order allow,deny 154 Allow from all 155 # or "Allow from yourschool.edu" 156 157 Examples 158 159 * Example 1: Standard setup 160 * Example 2: Virtual host setup 161 162 Example 1: Standard setup 163 164 You'll probably want this one. 165 166 # Define the location that is handled by the Apache::WeBWorK module, and tell 167 # perl where to find the libraries Apache::WeBWorK will need to run: 168 # 169 <Location /webwork2> 170 PerlSetVar webwork_root /opt/webwork2 171 PerlSetVar pg_root /opt/pg 172 <Perl> 173 use lib "/opt/webwork2/lib" 174 use lib "/opt/pg/lib" 175 </Perl> 176 SetHandler perl-script 177 PerlHandler Apache::WeBWorK 178 </Location> 179 180 # Provide access to system-wide resources: 181 # 182 Alias /webwork2_files /opt/webwork2/htdocs 183 <Directory /opt/webwork2/htdocs> 184 Options None 185 AllowOverride None 186 </Directory> 187 188 # Provide access to course-specific resources: 189 # 190 AliasMatch /webwork2_courses/([^/]*)/(.*) /opt/webwork2/courses/$1/html/$2 191 <Directory /opt/webwork2/courses/*/html> 192 Options FollowSymLinks 193 AllowOverride None 194 </Directory> 195 196 Example 2: Virtual host setup 197 198 This setup configures the root location (/) on a particular name-based 199 virtual host to be handled by Apache::WeBWorK. Please note that in this 200 setup, you would not be able to name a course files or courses. (Not that 201 you'd want to.) 202 203 NameVirtualHost * 204 205 <VirtualHost *> 206 207 ServerName webwork2.yourschool.edu 208 209 # Define the location that is handled by the Apache::WeBWorK module, and tell 210 # perl where to find the libraries Apache::WeBWorK will need to run: 211 # 212 <Location /> 213 PerlSetVar webwork_root /opt/webwork2 214 PerlSetVar pg_root /opt/pg 215 <Perl> 216 use lib "/opt/webwork2/lib" 217 use lib "/opt/pg/lib" 218 </Perl> 219 SetHandler perl-script 220 PerlHandler Apache::WeBWorK 221 </Location> 222 223 # Provide access to system-wide resources: 224 # 225 Alias /files /opt/webwork2/htdocs 226 <Directory /opt/webwork2/htdocs> 227 Options None 228 AllowOverride None 229 </Directory> 230 231 # Provide access to course-specific resources: 232 # 233 AliasMatch /courses/([^/]*)/(.*) /opt/webwork2/courses/$1/html/$2 234 <Directory /opt/webwork2/courses/*/html> 235 Options FollowSymLinks 236 AllowOverride None 237 </Directory> 238 239 </VirtualHost> 240 241 ____WEBWORK CONFIGURATION_______________________________________________________ 242 243 There are two sources of configuration information for a WeBWorK 244 installation. The global.conf file provides defaults for the entire 245 system, while the optional course.conf file overrides those values for a 246 particular course. Both of these files contain nested Perl data structures 247 which define the locations of files and directories, URLs, paths to 248 external programs, and other settings. 249 250 The configuration files are evaluated every time a request is made, so 251 configuration parameters can depend on certain properties of the request. 252 The following variables are made available in the configuration files: 253 254 +------------------------------------------------------------------------+ 255 | variable | description | 256 |------------+-----------------------------------------------------------| 257 |$webworkRoot|The base directory of the WeBWorK installation (i.e. | 258 | |/opt/webwork2) | 259 |------------+-----------------------------------------------------------| 260 |$webworkURL |The base URL handled by the Apache::WeBWorK mod_perl | 261 | |handler (i.e. /webwork2) | 262 |------------+-----------------------------------------------------------| 263 |$pgRoot |The base directory of the PG installation (i.e. /opt/pg) | 264 |------------+-----------------------------------------------------------| 265 |$courseName |The name of the course currently being requested (i.e. | 266 | |mth143) | 267 +------------------------------------------------------------------------+ 268 269 Overriding values in course.conf 270 271 Any value defined in global.conf can be overriddden on a per-course basis 272 in the file course.conf, located in each course's directory. This file is 273 optional, it can be empty or nonexistent. It has the same format as 274 global.conf. This is commonly used for overriding the database layout for 275 a course, and values like pg : specialPGEnvironmentVars : 276 PRINT_FILE_NAMES_FOR that depend on user IDs specific to a course. 277 278 To override some value in a course.conf file, change only the particular 279 hash key. For example, to override the PRINT_FILE_NAMES_FOR setting, put 280 the following in course.conf: 281 282 $pg->{specialPGEnvironmentVars}->{PRINT_FILE_NAMES_FOR} = ["new", "list", "of", "names"]; 283 284 Since the value of PRINT_FILE_NAMES_FOR is a list, you could also append a 285 value to it using the following perl construction: 286 287 push @{ $pg->{specialPGEnvironmentVars}->{PRINT_FILE_NAMES_FOR} }, "new"; 288 289 It might be helpful to consult Chapter 9, Data Structures, of the third 290 edition of the Camel Book for more information about nested data 291 structures. (The chapter is also illictly available on the web.) 292 293 Commonly modified global.conf values 294 295 Most values defined in global.conf need not be changed from their 296 defaults. Some values of interest include: 297 298 +------------------------------------------------------------------------+ 299 | value | description | 300 |-------------------------------+----------------------------------------| 301 | |The path to the courses directory. You | 302 | |might want to change this if you're | 303 |webworkDirs : courses |sharing courses with a WW1 installation,| 304 | |or if you wish to keep your courses | 305 | |somewhere else. (i.e. | 306 | |/var/lib/webwork/courses) | 307 |-------------------------------+----------------------------------------| 308 | |The URL of WeBWorK documentation, used | 309 |webworkURLs : docs |for the "Help" link. You may wish to | 310 | |change this if you have local | 311 | |documentation. | 312 |-------------------------------+----------------------------------------| 313 | |The URL of a WW1 profLogin.pl script, | 314 | |used for the "WeBWorK 1.x Instructor | 315 | |Tools" link. The script referenced | 316 |webworkURLs : oldProf |should have access to the same courses | 317 | |as this system. The user ID and session | 318 | |key of the current user are added to | 319 | |this URL to provide a seamless | 320 | |transition. | 321 |-------------------------------+----------------------------------------| 322 |mail : smtpServer |The SMTP server to use when sending | 323 | |email. Use an SMTP server at your site. | 324 |-------------------------------+----------------------------------------| 325 | |The "sender" address to pass to the SMTP| 326 |mail : smtpSender |server. This differs from the "from" | 327 | |address. Set this to some administrative| 328 | |address. | 329 |-------------------------------+----------------------------------------| 330 | |The full paths to external programs used| 331 |externalPrograms |by the system. Set the values in this | 332 | |hash to the paths appropriate fro your | 333 | |site. | 334 |-------------------------------+----------------------------------------| 335 | |The HTML template to use for arranging | 336 |templates : system |elements on generated pages. If you | 337 | |create your own site-specific template, | 338 | |specify the path to it here. | 339 |-------------------------------+----------------------------------------| 340 |permissionLevels |Use this hash to map capabilities to | 341 | |permission levels. | 342 |-------------------------------+----------------------------------------| 343 |pg : renderer |Set this to WeBWorK::PG::Remote to use a| 344 | |remote "renderd" renderer. | 345 |-------------------------------+----------------------------------------| 346 |pg : options |Use this hash to change the default PG | 347 | |options. | 348 |-------------------------------+----------------------------------------| 349 |pg : options : displayMode |Can be images, formattedText, or | 350 | |plainText | 351 |-------------------------------+----------------------------------------| 352 |pg : specialPGEnvironmentVars :|List the user IDs of users who should | 353 |PRINT_FILE_NAMES_FOR |get PG source file names in their | 354 | |rendered problems. | 355 +------------------------------------------------------------------------+ 356 357 Database options 358 359 The database configuration is controlled by the dbLayout hash. Various 360 versions of this hash are defined in separate configuration files, which 361 may be included using the include function. The database configuration 362 files are as follows: 363 364 +------------------------------------------------------------------------+ 365 | file | description | 366 |---------+--------------------------------------------------------------| 367 | |Defines dbLayout to use GDBM databases stored in the DATA | 368 |gdbm.conf|subdirectory of each course's directory. Suitable for courses | 369 | |that were created under WW1, or course that are to be shared | 370 | |between WW1 and WW2. | 371 |---------+--------------------------------------------------------------| 372 |sql.conf |Defines dbLayout to use a database on an SQL server. Suitable | 373 | |for courses that will only be used under WW2. | 374 +------------------------------------------------------------------------+ 375 376 What database layout configuration file you chose for the global default 377 (i.e. include into global.conf) depends on what database backend your 378 courses will usually use. Courses with a different database layout will 379 require a different configuration file to be included into that course's 380 course.conf file. 381 382 Please note: support for GDBM databases are provided only for backwards 383 compatability with courses used under WeBWorK 1.x and will be dropped in a 384 future version of WeBWorK 2 (as will all non-SQL database support). 385 386 ____COURSE CREATION_____________________________________________________________ 387 388 Database layouts 389 390 * The sql database layout specifies that all WeBWorK tables will be 391 stored as tables in an SQL database. Access is through the DBI module, 392 so (theoretically) any DBD:: module can be used. The sql layout 393 provides the fastest and most scalable performance. However, it 394 requires access to an SQL server. 395 * The gdbm database layout specifies that all WeBWorK tables will be 396 stored in a manner compatible with WeBWorK 1.x. That is, the data will 397 be stored in several GDBM databases within the course directory 398 itself. This layout provides compatability with WW1, but is 399 significantly slower and relies on fragile hacks to make it work. This 400 layout will not be supported in future releases of WeBWorK. 401 402 We suggest using the sql layout for new courses, unless compatability with 403 WW1 is necessary. 404 405 The default database layout for the system is stored in global.conf. It 406 can be changed on a per-course basis in that course's course.conf file. A 407 full discussion of this feature is available in the database.conf and 408 global.conf files in your distribution. 409 410 Database creation (SQL courses only) 411 412 For SQL courses, use the mksqldb utility to generate SQL statements that, 413 when executed, will create a course database. The output of mksqldb can be 414 piped directly to your SQL console. For example: 415 416 mksqldb myCourseName | mysql -u root -p 417 418 The mksqldb utility has some internal documentation that you may want to 419 consult. 420 421 Access privileges 422 423 You must also grant access privileges to two SQL accounts, webworkRead and 424 webworkWrite. webworkRead should have permission to SELECT. webworkWrite 425 should have permission to SELECT, INSERT, UPDATE, and DELETE. The 426 passwords for these accounts are defined in database.conf, and are blank 427 by default. This is because passwords entered here are both readable by 428 the web server and added to the course environment. Although we don't know 429 of any way that these values could "leak" out, one might exist. 430 431 If you have a dedicated machine for WeBWorK (with it's own IP address), it 432 is "safe" to leave those passwords blank and instead rely on IP-based 433 authentication. For example, at Rochester we grant access this way: 434 435 GRANT SELECT on webwork_myCourseName.* to webworkRead.localhost; 436 GRANT SELECT, INSERT, UPDATE, DELETE on webwork_myCourseName.* to webworkWrite.localhost; 437 438 Further discussion at SecurityIssues. 439 440 Course creation 441 442 Use the addcourse utility to create a new course directory, populate it 443 with problem templates (PG files), fill the database with users, and mark 444 some users as professors. The syntax of the utility is as follows: 445 446 addcourse [--templates=DIR] [--db-layout=LAYOUT] 447 [--users=FILE [--professors=USERID[,USERID]...] ] 448 COURSEID 449 450 All options are optional. Heh. 451 452 --templates=DIR 453 The contents of the directory DIR will be copied to the templates 454 directory of the new course. 455 456 --db-layout=LAYOUT 457 The specified database layout will be used in place of the default 458 specified in global.conf. 459 460 --users=FILE 461 The users listed in the comma-separated text file FILE will be 462 added to the user list of the new course. The format of this file 463 is the same as user lists exported from WeBWorK. 464 465 --professors=USERID[,USERID]... 466 Each USERID, if it is present in the new course's user list, will 467 be granted professor privileges (i.e. a permission level of 10). 468 Requires --users. 469 470 If you use --db-layout to override the default layout, you will need to 471 manually create a course.conf file in the new course's directory after 472 creating the course. The file should contain the following line: 473 474 *dbLayout = $dbLayouts{layoutName}; 475 476 This is described in greater detail in the global.conf and database.conf 477 files. 478 479 A default classlist file named defaultClasslist.lst is provided in the 480 courses directory. Templates can be obtained from various problem 481 libraries. 482 483 For example, I just created a course using the following commands: 484 485 $ cd /opt/webwork2 486 $ mysql -u root -p 487 mysql> GRANT SELECT on webwork_sqltest.* to webworkRead.localhost; 488 mysql> GRANT SELECT, INSERT, UPDATE, DELETE on webwork_sqltest.* to webworkWrite.localhost; 489 mysql> ^D 490 $ bin/mksqldb sqltest | mysql -u root -p 491 $ bin/addcourse --templates=/opt/problibs/rochester_problib --db-layout=sql \ 492 > --users=courses/defaultClasslist.lst --professors=professor
| aubreyja at gmail dot com | ViewVC Help |
| Powered by ViewVC 1.0.9 |