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