[system] / trunk / webwork2 / README Repository:
ViewVC logotype

Diff of /trunk/webwork2/README

Parent Directory Parent Directory | Revision Log Revision Log | View Patch Patch

Revision 1806 Revision 1807
… …
4 Version 2.0 4 Version 2.0
5 5
6 Copyright 2000-2004, The WeBWorK Project 6 Copyright 2000-2004, The WeBWorK Project
7 All rights reserved. 7 All rights reserved.
8 8
9The contents of this file were pulled from the WeBWorK wiki on 04-January-2004. 9 * [1]Introduction
10The latest version is available at http://devel.webwork.rochester.edu/. In this 10 * [2]Availability
11document: 11 * [3]Installation
12 * [4]Help
13 * [5]Bug Reports & Feature Requests
14 * [6]Patches
12 15
13 DESCRIPTION 16Introduction
14 SYSTEM REQUIREMENTS
15 INSTALLATION
16 APACHE CONFIGURATION
17 WEBWORK CONFIGURATION
18 COURSE CREATION
19 17
20____DESCRIPTION_________________________________________________________________ 18 The [7]WeBWorK Team is pleased to announce the release of [8]WeBWorK
19 2.0 Preview Release 3. While it is intended primarily for testing,
20 development, and evaluation of the new system, it is also suitable for
21 use in live courses.
21 22
22 WeBWorK is a Perl-based system for delivering individualized homework 23 This release includes almost all of the functionality of WeBWorK 1.9,
23 problems over the web. By providing students with immediate feedback as to 24 and contains new functionality beyond what it possible with 1.9. New
24 the correctness of their answers, students are encouraged to make multiple 25 features since [9]PreviewRelease2 include:
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 26
29____SYSTEM REQUIREMENTS_________________________________________________________ 27 * improvements in speed and efficiency
28 * many user interface enhancements
29 * improved course creation procedure
30 * "remember me" cookie actually works
31 * installation documentation improvements
32 * many bug fixes
30 33
31 Here are the software packages required by WeBWorK 2. Most OS vendors 34Availability
32 precompiled binaries of these packages. The version requirements given
33 below are somewhat imprecise.
34 35
35+-----------------------------------------------------------------------------------+ 36 The complete system is distributed as two tarballs. One for the
36| Package | Required For | Source |Version| 37 WeBWorK system itself, and one for the PG system, including a standard
37|-----------+----------------+----------------------------------------------+-------| 38 set of PG modules and macro files.
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 39
61 Perl must be compiled with GDBM support to use GDBM databases. (WeBWorK 40 Files are available below and on our SourceForge project page:
62 1.x databases are usually GDBM.) Most OS vendors compile their perl 41 [10]http://sourceforge.net/project/showfiles.php?group_id=93112
63 packages with this option on.
64 42
65 Also, some perl modules are required. All are available in CPAN, and many 43Installation
66 OS vendors provide packages of these modules.
67 44
68 * For WeBWorK 2 45 Documentation on installing and configuring WeBWorK is available on
46 this wiki. The relevant wiki topics are as follows:
69 47
70 * Bundle::Apache 48 * Installing Webwork
71 * DBI and the DBD:: module of your choice (required if you wish to 49 + Step 1: [11]SystemRequirements - satisfy system requirements.
72 use an SQL database backend) 50 + Step 2: [12]DirectorySetup - download and unpack the WeBWorK
73 * Data::UUID 51 distribution.
74 * Date::Format and Date::Parse 52 + Step 3: [13]ApacheSetup - configure apache.
75 * Mail::Sender 53 + Step 4: [14]TestCourse - create a test course to verify your
76 * SOAP::Lite (required if you wish to use a remote renderer) 54 installation.
55 + Step 5: [15]SystemConfig - customize your system
56 configuration.
57 + Step 6: [16]MiscConfig - customize miscellaneous
58 system-dependant settings.
59 * Creating and Upgrading Courses
60 + [17]CourseCreation - creating a new course.
61 + [18]CourseUpgrade - preparing a course from WeBWorK 1.x for
62 use under WeBWorK 2.0.
77 63
78 * For PG (required if you wish to use a local renderer) 64Help
79 65
80 * GD 66 If you need help installing or using [19]WeBWorK 2.0, visit the
67 [20]WeBWorK discussion group and post your question there. The
68 developers monitor this forum.
81 69
82____INSTALLATION________________________________________________________________ 70Bug Reports & Feature Requests
83 71
84Unpacking from CVS 72 Submit bug reports and feature requests at
73 [21]http://bugs.webwork.rochester.edu/. We can't fix bugs and add
74 features if you don't tell us about them!
85 75
86 A WeBWorK installation currently consists of two directory trees, a 76Patches
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 77
92 $ cvs checkout -P webwork-modperl 78 While we welcome patches of any sort, by patching against the latest
93 $ cvs checkout -P pg 79 CVS code, you save us and yourself time. A bug in Preview Release 3
80 may be fixed in CVS, and we can more easily handle patches against the
81 latest code. Check out the latest development version from CVS and
82 patch against that. Consult the [22]WeBWorKCVS topic for more
83 information.
94 84
95Unpacking from tarballs 85References
96 86
97 First, download the two tarballs: webwork-X.X.tar.bz2 and pg-X.X.tar.bz2. 87 1. http://devel.webwork.rochester.edu/twiki/bin/view/Webwork/PreviewRelease3#Introduction
98 ("X.X" represents the version number, i.e. "2.0pr2".) These files are 88 2. http://devel.webwork.rochester.edu/twiki/bin/view/Webwork/PreviewRelease3#Availability
99 available from our SourceForge project page: 89 3. http://devel.webwork.rochester.edu/twiki/bin/view/Webwork/PreviewRelease3#Installation
90 4. http://devel.webwork.rochester.edu/twiki/bin/view/Webwork/PreviewRelease3#Help
91 5. http://devel.webwork.rochester.edu/twiki/bin/view/Webwork/PreviewRelease3#Bug_Reports_Feature_Requests
92 6. http://devel.webwork.rochester.edu/twiki/bin/view/Webwork/PreviewRelease3#Patches
93 7. http://devel.webwork.rochester.edu/twiki/bin/view/Webwork/WeBWorK
94 8. http://devel.webwork.rochester.edu/twiki/bin/view/Webwork/WeBWorK
95 9. http://devel.webwork.rochester.edu/twiki/bin/view/Webwork/PreviewRelease2
100 http://sourceforge.net/project/showfiles.php?group_id=93112 96 10. http://sourceforge.net/project/showfiles.php?group_id=93112
101 97 11. http://devel.webwork.rochester.edu/twiki/bin/view/Webwork/SystemRequirements
102 Untar them somewhere (like your home directory). 98 12. http://devel.webwork.rochester.edu/twiki/bin/view/Webwork/DirectorySetup
103 99 13. http://devel.webwork.rochester.edu/twiki/bin/view/Webwork/ApacheSetup
104 $ tar -xjf webwork-2.0pr2.tar.bz2 100 14. http://devel.webwork.rochester.edu/twiki/bin/view/Webwork/TestCourse
105 $ tar -xjf pg-2.0pr2.tar.bz2 101 15. http://devel.webwork.rochester.edu/twiki/bin/view/Webwork/SystemConfig
106 102 16. http://devel.webwork.rochester.edu/twiki/bin/view/Webwork/MiscConfig
107 Then, become root and move the directories to the your installation 103 17. http://devel.webwork.rochester.edu/twiki/bin/view/Webwork/CourseCreation
108 directory. I prefer to use /opt. 104 18. http://devel.webwork.rochester.edu/twiki/bin/view/Webwork/CourseUpgrade
109 105 19. http://devel.webwork.rochester.edu/twiki/bin/view/Webwork/WeBWorK
110 # cp -r webwork-2.0pr2 /opt 106 20. http://webhost.math.rochester.edu/webworkdocs/discuss/
111 # cp -r pg-2.0pr2 /opt 107 21. http://bugs.webwork.rochester.edu/
112 108 22. http://devel.webwork.rochester.edu/twiki/bin/view/Webwork/WeBWorKCVS
113System 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
157Examples
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
269Overriding 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
293Commonly 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
357Database 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
388Database 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
410Database 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
440Course 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
Legend:
Removed from v.1806  
changed lines
  Added in v.1807
aubreyja at gmail dot com
 ViewVC Help
Powered by ViewVC 1.0.9