1 Webware's CGI Adapter
2 =====================
3
4 Copy the Webware/WebKit/Adapters/WebKit.cgi file to your CGI directory (eg.
5 /home/httpd/cgi-bin) and ensure that the permissions are appropriate for a CGI
6 program.
7
8 Configuring in Apache
9 ---------------------
10
11 Add a line like this to your Apache configuration file (eg. httpd.conf):
12
13 ScriptAlias /webkit "/home/httpd/cgi-bin/WebKit.cgi"
14
15 Configuring in AOLserver
16 ------------------------
17
18 Ensure the presence of the following lines in your configuration file (eg.
19 config.tcl):
20
21 ns_section "ns/server/${servername}/module/nscgi"
22 ns_param map "GET /webkit /home/httpd/cgi-bin/WebKit.cgi" ;# CGI script file dir (GET).
23 ns_param map "POST /webkit /home/httpd/cgi-bin/WebKit.cgi" ;# CGI script file dir (POST).
24 ns_param interps CGIinterps
25
26 ns_section "ns/interps/CGIinterps"
27 ns_param .cgi "/usr/bin/python"
28
29 See docs/CGI/NOTES.txt for more information on AOLserver and CGI
30 configuration.
31
32 Authentication/Authorisation in Webware
33 =======================================
34
35 Since Webware provides some kind of CGI emulation environment, the actual HTTP
36 headers involved with authentication/authorisation are not available to the
37 WebStack transaction. Therefore, WebStack depends on Webware having access to
38 the REMOTE_USER environment variable set by the Web server, and with Apache,
39 this variable is only ever set when Apache itself has performed
40 authentication. Whilst applications can send the "WWW-Authenticate" header to
41 HTTP clients, unless Apache has been instructed to process the resulting
42 username/password information, the REMOTE_USER will apparently remain
43 undefined.
44
45 Consequently, it is recommended that the following kind of definition is added
46 to httpd.conf (for Apache) in order to give applications access to
47 username/password details:
48
49 <Location "/webkit/auth">
50 AuthType Basic
51 AuthName "AuthResource"
52 AuthUserFile /usr/local/apache2/conf/users
53 require valid-user
54 </Location>
55
56 The details of the application's deployment, including the exact pathname of
57 the users file and the appropriate access policy, must obviously be defined
58 according to the actual application concerned.
59
60 Note that the above example will only apply authentication to either a
61 specific context (for Webware releases beyond 0.8.1) and only to a specific
62 "region" of possible URLs (for Webware 0.8.1 and earlier).
63
64 For Webware Releases Beyond 0.8.1
65 =================================
66
67 WebStack applications are supported as contexts within WebKit, meaning that a
68 certain prefix in the URL determines whether an application is sent a
69 particular request.
70
71 Each context must be defined in the Webware/WebKit/Configs/Application.config
72 file within the 'Contexts' dictionary; for example:
73
74 Contexts['simple'] = '/home/paulb/Software/Python/WebStack/examples/Webware/SimpleContext'
75
76 Note that the path to the context directory must be absolute, although the
77 context directory may reside within WebKit itself such that the path may then
78 make use of the special WebKitPath variable.
79
80 Note also that the name of the context (eg. 'simple') must not be the same as
81 the name of any other package used within the application (and possibly any
82 other applications in the application server), with the only reasonable
83 exception being the context package name itself (eg. 'SimpleContext').
84 Otherwise, the existing package will become overridden by the contents of the
85 context itself. Therefore, given that the Simple package is used to hold the
86 actual application code, it is not wise to use 'Simple' as the context name.
87
88 Running the application server:
89
90 Change into the WebKit directory within Webware. Then, specifying the
91 appropriate PYTHONPATH, invoke the application server. For example:
92
93 PYTHONPATH=../../WebStack:../../WebStack/examples/Common ./AppServer
94
95 The WebStack package must reside on the PYTHONPATH, along with the package
96 containing the application itself.
97
98 For Webware 0.8.1 or Earlier
99 ============================
100
101 Support for WebStack applications is provided by a Webware plug-in which
102 associates Webware resources having certain suffixes with certain WebStack
103 applications, regardless of the context within which a resource appears. In
104 order to make use of such a scheme, a WebStack application would have its
105 resources residing in an arbitrary URL "hierarchy", but with each resource
106 having the special suffix to indicate that it belongs to that application.
107
108 In the case of an application whose chosen suffix is ".xyz", it would be
109 possible, for example, to define resources residing at the following URL
110 paths:
111
112 tasks/my-tasks.xyz
113 tasks/outstanding/urgent.xyz
114 agenda/today.xyz
115
116 This is somewhat counter-intuitive to typical Webware concepts, and it is
117 recommended that Webware releases beyond 0.8.1 are used together with the
118 appropriate WebStack context mechanisms instead of using this plug-in scheme.
119
120 In order to support such behaviour, the patches in the
121 WebStack/patches/Webware/WebKit directory must be applied to WebKit:
122
123 cd Webware/WebKit
124 patch -p0 < ../../WebStack/patches/Webware/WebKit/Application.py-0.8.1.diff
125 patch -p0 < ../../WebStack/patches/Webware/WebKit/HTTPRequest.py-0.8.1.diff
126
127 Each plug-in, representing a WebStack application, should be visible in the
128 Webware root directory. A symbolic link can be used to make each example
129 appear; the Simple application being installed as follows:
130
131 cd Webware
132 ln -s ../WebStack/examples/Webware/SimpleApp
133
134 Configuring the application server:
135
136 Ensure that the ExtraPathInfo parameter in WebKit/Configs/Application.config
137 is set to 0.
138
139 Running the application server:
140
141 Change into the WebKit directory within Webware. Then, specifying the
142 appropriate PYTHONPATH, invoke the application server. For example:
143
144 PYTHONPATH=../../WebStack:../../WebStack/examples/Common ./AppServer
145
146 The WebStack package must reside on the PYTHONPATH, along with the package
147 containing the application itself.