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