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