1.1 --- /dev/null Thu Jan 01 00:00:00 1970 +0000
1.2 +++ b/docs/deploying-applications.html Sat Apr 09 12:32:28 2005 +0000
1.3 @@ -0,0 +1,87 @@
1.4 +<?xml version="1.0" encoding="iso-8859-1"?>
1.5 +<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN"
1.6 + "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">
1.7 +<html xmlns="http://www.w3.org/1999/xhtml">
1.8 +<head>
1.9 + <title>Deploying an Application</title>
1.10 + <meta name="generator" content="amaya 8.1a, see http://www.w3.org/Amaya/" />
1.11 + <link href="styles.css" rel="stylesheet" type="text/css" />
1.12 +</head>
1.13 +
1.14 +<body>
1.15 +<h1>Deploying an Application</h1>
1.16 +
1.17 +<p>Here is a table which summarises the steps required to actually deploy
1.18 +your application in the different server environments or frameworks:</p>
1.19 +
1.20 +<table border="1" cellspacing="0" cellpadding="5">
1.21 + <tbody>
1.22 + <tr>
1.23 + <th>Framework</th>
1.24 + <th>Deployment Steps</th>
1.25 + </tr>
1.26 + <tr>
1.27 + <td>BaseHTTPRequestHandler</td>
1.28 + <td>Just run the adapter code</td>
1.29 + </tr>
1.30 + <tr>
1.31 + <td>CGI</td>
1.32 + <td>Declare a script directory in the Web server<br />
1.33 + Deploy application code in the specified script directory<br />
1.34 + Restart the Web server</td>
1.35 + </tr>
1.36 + <tr>
1.37 + <td>Java Servlet</td>
1.38 + <td>Use the supplied script in <code>tools/JavaServlet</code> and
1.39 + follow your servlet container's instructions</td>
1.40 + </tr>
1.41 + <tr>
1.42 + <td>mod_python</td>
1.43 + <td>Declare a handler directory in Apache<br />
1.44 + Deploy application code in the specified handler directory<br />
1.45 + Restart Apache</td>
1.46 + </tr>
1.47 + <tr>
1.48 + <td>Twisted</td>
1.49 + <td>Just run the adapter code</td>
1.50 + </tr>
1.51 + <tr>
1.52 + <td>Webware</td>
1.53 + <td>Copy or symbolically link your application code directory to reside
1.54 + alongside other Webware plug-ins<br />
1.55 + Configure your application within Webware<br />
1.56 + Start Webware</td>
1.57 + </tr>
1.58 + <tr>
1.59 + <td>WSGI</td>
1.60 + <td>(Follow the instructions for CGI - this may change in future.)</td>
1.61 + </tr>
1.62 + <tr>
1.63 + <td>Zope</td>
1.64 + <td>Copy or symbolically link your application code directory to reside
1.65 + in the Zope <code>Products</code> directory<br />
1.66 + Configure <code>etc/zope.conf</code><br />
1.67 + Start Zope<br />
1.68 + Add a product instance for your application at the desired location
1.69 + in the Zope filesystem</td>
1.70 + </tr>
1.71 + </tbody>
1.72 +</table>
1.73 +
1.74 +<h2>More Information</h2>
1.75 +
1.76 +<p>Notes on each server environment can be found in subdirectories within the
1.77 +<code>docs</code> directory:</p>
1.78 +<ul>
1.79 + <li><a
1.80 + href="BaseHTTPRequestHandler/NOTES.txt">BaseHTTPRequestHandler</a></li>
1.81 + <li><a href="CGI/NOTES.txt">CGI</a></li>
1.82 + <li><a href="JavaServlet/NOTES.txt">Java Servlet</a></li>
1.83 + <li><a href="ModPython/NOTES.txt">mod_python</a></li>
1.84 + <li><a href="Twisted/NOTES.txt">Twisted</a></li>
1.85 + <li><a href="Webware/NOTES.txt">Webware</a></li>
1.86 + <li><a href="WSGI/NOTES.txt">WSGI</a></li>
1.87 + <li><a href="Zope/NOTES.txt">Zope</a></li>
1.88 +</ul>
1.89 +</body>
1.90 +</html>
2.1 --- a/docs/deploying.html Fri Apr 08 23:11:22 2005 +0000
2.2 +++ b/docs/deploying.html Sat Apr 09 12:32:28 2005 +0000
2.3 @@ -1,6 +1,6 @@
2.4 <?xml version="1.0" encoding="iso-8859-1"?>
2.5 <!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN"
2.6 - "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">
2.7 + "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">
2.8 <html xmlns="http://www.w3.org/1999/xhtml">
2.9 <head>
2.10 <title>Deploying a WebStack Application</title>
2.11 @@ -9,70 +9,87 @@
2.12 </head>
2.13
2.14 <body>
2.15 -<h1>Deploying a WebStack Application<br />
2.16 -</h1>
2.17 +<h1>Deploying a WebStack Application</h1>
2.18 +
2.19 +<p>The process of deploying a WebStack application should be as
2.20 +straightforward as taking some adapter or "glue" code and either running it
2.21 +or using the deployment processes of the server environment or framework in
2.22 +which the application will be living.</p>
2.23 +
2.24 +<h2>The Adapter Code</h2>
2.25
2.26 -<p>When deploying an application, it is possible to use a one-shot deploy
2.27 -function for certain frameworks. The <code>deploy</code> function is called
2.28 -as follows:</p>
2.29 -<pre>deploy(resource)
2.30 -deploy(resource, authenticator) # where authenticators are used</pre>
2.31 +<p>What adapter or "glue" code does is to set up your applications main
2.32 +resource object and to hook that object up with the underlying server
2.33 +environment. It typically looks something like this:</p>
2.34 +<pre>from WebStack.Adapters.CGI import deploy # import the support for the server environment
2.35 +from MyApplication import MyResource # import the main resource class
2.36 +deploy(MyResource()) # connect a resource object to the server environment</pre>
2.37
2.38 -<p>For some frameworks, an address may be specified:</p>
2.39 -<pre>deploy(resource, address=(host_string, port_integer))
2.40 -deploy(resource, authenticator, address=(host_string, port_integer))</pre>
2.41 +<p>Unfortunately, not all server environments can be connected up with
2.42 +applications this easily. Some environments require special classes and
2.43 +functions to be defined in the adapter code in order for the applications to
2.44 +be properly integrated into the environments. Here is a summary which
2.45 +indicates the server environments or frameworks which need most work:</p>
2.46
2.47 -<table border="1" cellpadding="5" cellspacing="0">
2.48 +<table border="1" cellspacing="0" cellpadding="5">
2.49 <tbody>
2.50 <tr>
2.51 <th>Framework</th>
2.52 - <th>Address Information</th>
2.53 + <th>Adapter Code Requirements</th>
2.54 + <th>Deployment Process</th>
2.55 </tr>
2.56 <tr>
2.57 <td>BaseHTTPRequestHandler</td>
2.58 - <td>Supported</td>
2.59 + <td>Simple - see above</td>
2.60 + <td>Run the adapter code directly</td>
2.61 </tr>
2.62 <tr>
2.63 <td>CGI</td>
2.64 - <td>Ignored</td>
2.65 + <td>Simple - see above</td>
2.66 + <td>Web server runs the adapter code</td>
2.67 + </tr>
2.68 + <tr>
2.69 + <td>Java Servlet</td>
2.70 + <td>Must subclass <code>HttpServlet</code></td>
2.71 + <td>Application must be deployed using supplied tools</td>
2.72 + </tr>
2.73 + <tr>
2.74 + <td>mod_python</td>
2.75 + <td>Must implement <code>handler</code> function</td>
2.76 + <td>Web server runs the adapter code (which must be declared within
2.77 + Apache)</td>
2.78 </tr>
2.79 <tr>
2.80 <td>Twisted</td>
2.81 - <td>Supported (<code>host_string</code> is ignored)</td>
2.82 + <td>Simple - see above</td>
2.83 + <td>Run the adapter code directly</td>
2.84 + </tr>
2.85 + <tr>
2.86 + <td>Webware</td>
2.87 + <td><= 0.8.1: Must implement <code>InstallInWebKit</code>
2.88 + function<br />
2.89 + > 0.8.1: Simple, but must provide a <code>urlParser</code>
2.90 + object</td>
2.91 + <td>Application must be deployed within WebKit</td>
2.92 </tr>
2.93 <tr>
2.94 <td>WSGI</td>
2.95 - <td>Ignored</td>
2.96 + <td>Simple - see above</td>
2.97 + <td>Web server runs the adapter code</td>
2.98 + </tr>
2.99 + <tr>
2.100 + <td>Zope</td>
2.101 + <td>Must provide lots of Zope administative classes and functions</td>
2.102 + <td>Application must be deployed within Zope</td>
2.103 </tr>
2.104 </tbody>
2.105 </table>
2.106
2.107 -<p>The other frameworks do not support the deploy function due to the way
2.108 -applications are typically integrated into the various server mechanisms:</p>
2.109 -
2.110 -<table border="1" cellpadding="5" cellspacing="0">
2.111 - <tbody>
2.112 - <tr>
2.113 - <th>Framework</th>
2.114 - <th>Deployment Details</th>
2.115 - </tr>
2.116 - <tr>
2.117 - <td>JavaServlet</td>
2.118 - <td>Applications are packaged specially</td>
2.119 - </tr>
2.120 - <tr>
2.121 - <td>ModPython</td>
2.122 - <td>Applications must expose certain functions</td>
2.123 - </tr>
2.124 - <tr>
2.125 - <td>Webware</td>
2.126 - <td>Applications must expose certain classes</td>
2.127 - </tr>
2.128 - <tr>
2.129 - <td>Zope</td>
2.130 - <td>Applications must expose certain functions/classes</td>
2.131 - </tr>
2.132 - </tbody>
2.133 -</table>
2.134 +<h2>The Deployment Process</h2>
2.135 +<ul>
2.136 + <li><a href="writing-adapters.html">Writing Adapters</a></li>
2.137 + <li><a href="pythonpath.html">Getting PYTHONPATH Righ</a>t</li>
2.138 + <li><a href="deploying-applications.html">Deploying an Application</a></li>
2.139 +</ul>
2.140 </body>
2.141 </html>
3.1 --- /dev/null Thu Jan 01 00:00:00 1970 +0000
3.2 +++ b/docs/pythonpath.html Sat Apr 09 12:32:28 2005 +0000
3.3 @@ -0,0 +1,61 @@
3.4 +<?xml version="1.0" encoding="iso-8859-1"?>
3.5 +<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN"
3.6 + "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">
3.7 +<html xmlns="http://www.w3.org/1999/xhtml">
3.8 +<head>
3.9 + <title>Getting PYTHONPATH Right</title>
3.10 + <meta name="generator" content="amaya 8.1a, see http://www.w3.org/Amaya/" />
3.11 + <link href="styles.css" rel="stylesheet" type="text/css" />
3.12 +</head>
3.13 +
3.14 +<body>
3.15 +<h1>Getting PYTHONPATH Right</h1>
3.16 +
3.17 +<p>When deploying your application, it is essential that it has access to all
3.18 +the necessary libraries and packages that it uses. If such libraries and
3.19 +packages were installed using the standard <code>setup.py</code> program,
3.20 +then you may only need to worry about the application itself being found by
3.21 +Python.</p>
3.22 +
3.23 +<h2>Running Adapters Directly</h2>
3.24 +
3.25 +<p>For those server environments where you can just run the adapter code
3.26 +(BaseHTTPRequestHandler, Twisted), you can choose to specify the
3.27 +<code>PYTHONPATH</code> on the command line when you run the code. Here is an
3.28 +example of this (using <code>bash</code> on GNU/Linux or UNIX
3.29 +distributions):</p>
3.30 +<pre>PYTHONPATH=.:examples/Common python examples/BaseHTTPRequestHandler/SimpleApp.py</pre>
3.31 +
3.32 +<h2>Adapters Run by the Web Server</h2>
3.33 +
3.34 +<p>For those server environments where the Web server itself runs the adapter
3.35 +code (CGI, mod_python, WSGI), you may need to either configure the Web server
3.36 +to alter the <code>PYTHONPATH</code>, if possible, or to add some extra lines
3.37 +in the adapter code to change Python's <code>sys.path</code> variable. Here
3.38 +is an example of this:</p>
3.39 +<pre>sys.path.append("/home/paulb/Software/Python/WebStack/examples/Common")</pre>
3.40 +
3.41 +<h2>Configuring PYTHONPATH in Java Servlet Containers</h2>
3.42 +
3.43 +<p>In servlet container deployments, all required libraries and packages are
3.44 +typically bundled with the application itself. Since this bundling process is
3.45 +usually very inconvenient, a script has been included in the
3.46 +<code>tools/JavaServlet</code> directory to make it slightly easier.</p>
3.47 +
3.48 +<h2>Configuring PYTHONPATH in Webware</h2>
3.49 +
3.50 +<p>Since Webware's WebKit runs as a separate process, it is possible to
3.51 +specify <code>PYTHONPATH</code> on the command line when you start that
3.52 +process. Here is an example of this (using <code>bash</code> on GNU/Linux or
3.53 +UNIX distributions):</p>
3.54 +<pre>cd WebKit
3.55 +PYTHONPATH=/home/paulb/Software/Python/WebStack/examples/Common ./AppServer</pre>
3.56 +
3.57 +<h2>Configuring PYTHONPATH in Zope</h2>
3.58 +
3.59 +<p>In Zope's <code>etc/zope.conf</code> file, <code>path</code> directives
3.60 +can be used to indicate the location of various resources. Here is an example
3.61 +of this:</p>
3.62 +<pre>path /home/paulb/Software/Python/WebStack/examples/Common</pre>
3.63 +</body>
3.64 +</html>
4.1 --- /dev/null Thu Jan 01 00:00:00 1970 +0000
4.2 +++ b/docs/writing-adapters.html Sat Apr 09 12:32:28 2005 +0000
4.3 @@ -0,0 +1,67 @@
4.4 +<?xml version="1.0" encoding="iso-8859-1"?>
4.5 +<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN"
4.6 + "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">
4.7 +<html xmlns="http://www.w3.org/1999/xhtml">
4.8 +<head>
4.9 + <title>Writing Adapters</title>
4.10 + <meta name="generator" content="amaya 8.1a, see http://www.w3.org/Amaya/" />
4.11 + <link href="styles.css" rel="stylesheet" type="text/css" />
4.12 +</head>
4.13 +
4.14 +<body>
4.15 +<h1>Writing Adapters</h1>
4.16 +
4.17 +<p>Depending on how "simple" the adapter code is allowed to be for a given
4.18 +server environment (see the <a href="deploying.html">table</a> for a
4.19 +summary), you will either need to write a small piece of code which
4.20 +initialises and deploys your application, or to produce a more complicated
4.21 +piece of code which satisfies some more demanding server requirements.</p>
4.22 +
4.23 +<h2>Simple Adapters - Using the deploy Function</h2>
4.24 +
4.25 +<p>When deploying an application, it is possible to use a one-shot deployment
4.26 +function for BaseHTTPRequestServer, CGI, Twisted and WSGI. The
4.27 +<code>deploy</code> function is called as follows:</p>
4.28 +<pre>deploy(resource)
4.29 +deploy(resource, authenticator) # where authenticators are used</pre>
4.30 +
4.31 +<p>For some frameworks, an address may be specified:</p>
4.32 +<pre>deploy(resource, address=(host_string, port_integer))
4.33 +deploy(resource, authenticator, address=(host_string, port_integer))</pre>
4.34 +
4.35 +<p>Here is a summary of which frameworks require address information:</p>
4.36 +
4.37 +<table border="1" cellpadding="5" cellspacing="0">
4.38 + <tbody>
4.39 + <tr>
4.40 + <th>Framework</th>
4.41 + <th>Address Information</th>
4.42 + </tr>
4.43 + <tr>
4.44 + <td>BaseHTTPRequestHandler</td>
4.45 + <td>Supported</td>
4.46 + </tr>
4.47 + <tr>
4.48 + <td>CGI</td>
4.49 + <td>Ignored</td>
4.50 + </tr>
4.51 + <tr>
4.52 + <td>Twisted</td>
4.53 + <td>Supported (<code>host_string</code> is ignored)</td>
4.54 + </tr>
4.55 + <tr>
4.56 + <td>WSGI</td>
4.57 + <td>Ignored</td>
4.58 + </tr>
4.59 + </tbody>
4.60 +</table>
4.61 +
4.62 +<h2>Complicated Adapters - Providing Framework-Specific Objects</h2>
4.63 +
4.64 +<p>The remaining frameworks (Java Servlet, mod_python, Webware and Zope) do
4.65 +not support the <code>deploy</code> function due to the way applications are
4.66 +typically integrated into the various server mechanisms. In these cases, it
4.67 +may be worth investigating the examples provided and using their adapter code
4.68 +as a template for the code for your own applications.</p>
4.69 +</body>
4.70 +</html>