[ZDP] Win32Installation - Draft 2

kamon.ayeva@bureauveritas.com kamon.ayeva@bureauveritas.com
Fri, 8 Oct 1999 15:13:59 +0200


                       Zope Installation on Windows


System requirements

Pentium PC
Windows 95/NT
RAM 128 Mb minimum recommended for a production server


Installing Zope

What you need

You need to get the latest stable precompiled version of Zope for Windows
on the Zope.org site.

Installation steps

1.      Launch the self-extracting installation file using Windows Explorer
or from a DOS window.
2.      The Zope installation welcome window appears. Click next to go to
the Zope Public License terms and conditions page. Click Accept if you
understand them and agree.
3.      You will be prompted for a name for the site. This name will be
used, by default, as the name for the Zope installation top level
directory. So we suggest you choose ?Zope?. Click Next to continue.
4.      You will be asked to choose a location to install Zope. Change the
default location path to X:\WebSite, X: being the local drive reserved for
Zope. Click Next to continue.
5.      Finally, you will be prompted for a username and password to be
used for the super manager account. This is the account that will give you
complete access to the entire site. Pick a username and password, and click
Next. The installation program will begin copying files.
6.      If you are installing Zope on Windows NT, the installation program
will prompt you at this point whether you would like to have Zope started
automatically as an NT service or you would like to start Zope manually.
7.      When the installation is completed, click Finish to exit the
installer.

Starting Zope for the first time

·  Using Windows Explorer or from a DOS window, run the file start.bat in
X:\WebSite, to start Zope.
·  Start a browser installed on the same machine, and try to access the
server via the URL : ?http://localhost:8080/manage'
·  You will be prompted for the user name and password you provided during
the installation.
·  Enter this name and password and click OK. You will reach the Zope
Management interface which allows you to build and manage all the Zope site
objects.

Running Zserver

You can see Zope as a client-server system, where the client is the
browser, and the server is Zserver.
Zserver is Digital Creation?s integrated version of the high-performance,
multiprotocol Medusa server toolkit created by Sam Rushing.
ZServer allows you to access Zope objects through the main Web protocols :
HTTP, FTP, WebDAV, and LDAP. One other advantage of Zserver over
traditionnal web servers is that it is multi-threaded ? it can handle
multiple web requests at the same time.

When you start Zope/ZServer, you get three main processes started :

§  The HTTP server.         Medusa HTTP services
§  The FTP server.          Medusa FTP services
§  The secure Monitor server.    Allows interactive Python style access to
a running Zserver.

There are a number of options available when starting Zserver for the first
time, with a command of the type
C:\WebSite\bin\python.exe c:\WebSite\z2.py -D

You can edit the start.bat file provided for manually starting Zope and
place additional command line switches after the ? -D ?.

The following table gives you an overview of the most common Zserver
command line options. We will mention the other specific options when we
will be discussing their related topics.
|--------------------+---------------------------->
|                    |                            |
| Switch             | Purpose                    |
|                    |                            |
|--------------------+---------------------------->
  >---------------------------|
  |                           |
  | Default is?               |
  |                           |
  >---------------------------|
|--------------------+---------------------------->
|                    |                            |
| -h                 | To get help on the         |
|                    | available command options  |
|                    |                            |
|--------------------+---------------------------->
  >---------------------------|
  |                           |
  |                           |
  |                           |
  >---------------------------|
|--------------------+---------------------------->
|                    |                            |
| -z path            | The location of the Zope   |
|                    | installation.              |
|                    | Usefull when having        |
|                    | several instances of Zope  |
|                    | on the system ?            |
|                    |                            |
|--------------------+---------------------------->
  >---------------------------|
  |                           |
  | Set in the default        |
  | start.bat (e.g.           |
  | X:\WebSite)               |
  |                           |
  >---------------------------|
|--------------------+---------------------------->
|                    |                            |
| -t n               | To specify the number of   |
|                    | threads to use.            |
|                    |                            |
|--------------------+---------------------------->
  >---------------------------|
  |                           |
  | 4                         |
  |                           |
  >---------------------------|
|--------------------+---------------------------->
|                    |                            |
| -D                 | To run in Zope debug mode. |
|                    | This causes the Zope       |
|                    | process not to detach from |
|                    | the controlling terminal,  |
|                    | and is equivalent to       |
|                    | supplying the environment  |
|                    | variable setting           |
|                    | Z_DEBUG_MODE=1             |
|                    |                            |
|--------------------+---------------------------->
  >---------------------------|
  |                           |
  |                           |
  |                           |
  >---------------------------|
|--------------------+---------------------------->
|                    |                            |
| -a ipaddress       | The IP address to listen   |
|                    | on.                        |
|                    | If the value is an empty   |
|                    | string, then all adresses  |
|                    | on the machine are used.   |
|                    |                            |
|--------------------+---------------------------->
  >---------------------------|
  |                           |
  | .                         |
  |                           |
  >---------------------------|
|--------------------+---------------------------->
|                    |                            |
| -d ipaddress       | The IP address of your DNS |
|                    | server.                    |
|                    | If the value is an empty   |
|                    | string, then IP addresses  |
|                    | will not be logged.        |
|                    | If you have DNS service on |
|                    | your local machine, you    |
|                    | can set this to 127.0.0.1. |
|                    |                            |
|--------------------+---------------------------->
  >---------------------------|
  |                           |
  | .                         |
  |                           |
  >---------------------------|
|--------------------+---------------------------->
|                    |                            |
| -P number          | Set the http, ftp and      |
|                    | monitor port numbers       |
|                    | simultaneously as offsets  |
|                    | from the number.           |
|                    | The HTTP port will (number |
|                    | + 80),                     |
|                    | the FTP port will be       |
|                    | (number + 21),             |
|                    | and the Monitor port will  |
|                    | be (number + 99).          |
|                    |                            |
|--------------------+---------------------------->
  >---------------------------|
  |                           |
  | 8000                      |
  |                           |
  >---------------------------|
|--------------------+---------------------------->
|                    |                            |
| -w port            | The Zope HTTP (Web) port.  |
|                    | If the value is an empty   |
|                    | string, then HTTP is       |
|                    | disabled.                  |
|                    |                            |
|--------------------+---------------------------->
  >---------------------------|
  |                           |
  | 8080                      |
  | The standard port for     |
  | HTTP service is 80.       |
  |                           |
  >---------------------------|
|--------------------+---------------------------->
|                    |                            |
| -f port            | The Zope FTP port.         |
|                    | If the value is an empty   |
|                    | string, then FTP is        |
|                    | disabled.                  |
|                    |                            |
|--------------------+---------------------------->
  >---------------------------|
  |                           |
  | 8021                      |
  | The standard port for FTP |
  | service is 21.            |
  |                           |
  >---------------------------|
|--------------------+---------------------------->
|                    |                            |
| -m port            | The secure monitor server  |
|                    | port.                      |
|                    | If the value is an empty   |
|                    | string, then the monitor   |
|                    | server is disabled.        |

|                    |                            |
|--------------------+---------------------------->
  >---------------------------|
  |                           |
  | 8099                      |
  |                           |
  >---------------------------|
|--------------------+---------------------------->
|                    |                            |
| -l path            | Path to the Zserver log    |
|                    | file.                      |
|                    | If this is a relative      |
|                    | path, then the log file    |
|                    | will be written to the VAR |
|                    | directory.                 |
|                    |                            |
|--------------------+---------------------------->
  >---------------------------|
  |                           |
  | Z2.log                    |
  |                           |
  >---------------------------|
|--------------------+---------------------------->
|                    |                            |
|                    |                            |
|                    |                            |
|--------------------+---------------------------->
  >---------------------------|
  |                           |
  |                           |
  |                           |
  >---------------------------|





Zope with IIS integration

The integration of Zope with a third party Web server like IIS or Netscape
Web server may be needed in the following cases :

·  You already have a web server running that you cannot take down and you
cannot run Zserver on a different port.
·  You would like to protect all your Zope content with SSL.
·  You would like to use your existing web server to do such things as
advanced load balancing or map virtual hosts to different folders in the
Zope hierarchy.
·  You would like to run Zope on your ISP?s machine.

Before discussing this kind of Zope setup, let?s have a background session
on current standards of dynamic web content delivery techniques.

Background on CGI, Persistent CGI and the likes

CGI.         CGI or ? Common Gateway Interface ? is the de facto standard
interface for Web server applications, and was first implemented in the
NCSA server.

A typical CGI request processing proceeds as follows:

1.      The Web server creates a new process and the process initializes
itself.
2.      The Web server passes the request information (such as remote host,
username, HTTP headers, etc.) to the CGI program in environment variables.
3.      The Web server sends any client input (such as user-entered field
values from an HTML form) to the CGI program's standard input.
4.      The CGI program writes any output to be returned to the client on
standard output.
5.      When the CGI process exits, the request is complete.

The CGI method works for the majority of web applications with tasks such
as collecting input from a form and e-mailing it to somebody. However, with
this method, the web server must start the CGI script every time to process
the request. So there is a major performance issue with applications based
on ? non basic ? dynamic content processing.

With new generation web applications, tight integration of the Web server
and the components which retrieve and process data are important to surpass
the performance limitations of CGI-based systems. A number of public and
proprietary alternatives to CGI have been proposed, including Persistent
CGI, Fast-CGI, NSAPI (Netscape Server API), ISAPI (Internet Server API),
SAPI, and Apache API.

PCGI.        Persistent CGI or PCGI is a method originally developed by
Digital Creations to circumvent the process start up overhead that CGI
programs incur.

A typical PCGI request processing proceeds as follows:

1.      A small application known as the ? pcgi_wrapper ? forwards the Web
request from the web server to an external application (e.g. Zserver) via a
specified INET port.
2.      The external application processes the request and sends the
results back to the PCGI wrapper via the inet port.
3.      The PCGI wrapper then passes the results to the web server and
quits.
4.      Finally, the web server serve the results to the browser.

Note that there is a small hit with the process of launching the PCGI
wrapper, but it is small enough to not be noticed on any but the most
trafficked of sites.

With Zope, using PCGI allows you to forward requests from a third party web
server such as IIS 4.0 to Zserver.

Server APIs.      In response to the performance problems for CGI, several
vendors have developed APIs for their servers. The two most notable are
NSAPI from Netscape and ISAPI from Microsoft. Apache server also has an
API.

Applications linked into the server API may be significantly faster than
CGI programs. The CGI startup/initialization problem is improved, because
the application runs in the server process and is persistent across
requests.

Web server APIs also offer more functionality than CGI : you can write
extensions that perform access control, get access to the server's log
file, and link into other stages in the server's request processing.

FastCGI.     FastCGI is a solution to the CGI process launch problem,
developed by OpenMarket and that is almost identical to Digital Creations?
PCGI.

Request processing in a single-threaded FastCGI application proceeds as
follows:

1.      The Web server creates FastCGI application processes to handle
requests. The processes are created at startup.
2.      The FastCGI program initializes itself, and waits for a new
connection from the Web server.
3.      When a client request comes in, the Web server opens a connection
to the FastCGI process, and sends the CGI environment variable information
and standard input over the connection.
4.      The FastCGI process sends the standard output and error information
back to the server over the same connection.
5.      When the FastCGI process closes the connection, the request is
complete. The FastCGI process then waits for another connection from the
Web server.

Theoreticaly, FastCGI applications can be multithreaded, accepting multiple
connections from the Web server and
handling them simultaneously in a single process. However, current versions
of FastCGI application libraries do not support multi-threaded
applications.

FastCGI applications can run locally (on the same machine as the Web
server) or remotely. For local applications, the server uses a full-duplex
pipe to connect to the FastCGI application process. For remote
applications, the server uses a TCP connection.


Setting up Zope with IIS using PCGI

What you need

You need to get the latest stable precompiled version of Zope for Windows
on the Zope.org site.
IIS is only available with Windows NT 4. Windows NT Server includes a free
copy of Internet Information Server 2.0. You need to download
(http://www.microsoft.com) and install the Microsoft Options Pack to
upgrade your IIS to version 4.0.

Installation steps

1.      Install Zope the normal way.
2.      Copy over the Zope.cgi file from a non-Windows Zope distribution to
the IIS CGI scripts directory, e.g. X:\IIS\CGI-BIN. Rename the file to
zope.pcgi. This is the PCGI info file.
3.      Edit the PCGI info file, and change it to the following :
 [zope.pcgi file content]
 PCGI_NAME=Website
 PCGI_PORT=8090
 PCGI_MODULE_PATH="X:\WebSite\lib\python\Main.py"
 PCGI_PUBLISHER="X:\WebSite\pcgi\pcgi_publisher.py"
 PCGI_EXE="X:\WebSite\pcgi"
 PCGI_SOCKET_FILE="X:\WebSite\pcgi\pcgi.soc"
 PCGI_PID_FILE="X:\WebSite\pcgi\pcgi.pid"
 PCGI_ERROR_LOG="X:\WebSite\pcgi\pcgi.log"
 PCGI_DISPLAY_ERRORS=1
 BOBO_REALM=Zope
 BOBO_DEBUG_MODE=1
 INSTANCE_HOME="X:\WebSite"

4.      Instruct IIS to execute PCGI info files with the extension .pcgi as
CGI programs. To do that, yopu need to add an extension mapping to IIS : In
the Microsoft Management Console, select your site's Properties, and then
under the 'Home Directory' tab click on 'Configuration'. Now, add the
mapping : .pcgi  X:\WebSite\pcgi\Win32\pcgi-wrapper.exe  %s

Starting Zope for the first time

·  Modify the Zope startup script (start.bat) to the following :
C:\WebSite\bin\python.exe C:\WebSite\z2.py -D -p X:\IIS\CGI-BIN\zope.pcgi
·  If you installed Zope as a Windows NT Service, you will have to edit the
registry key:

HKEY_LOCAL_MACHINE\SYSTEM\CurrentControlSet\Services\
                     <Service Name>\Parameters\start

Add '-p X:\IIS\CGI-BIN\zope.pcgi' after ?start?.
·  Finally, make sure that IIS and Zope are both started up, and try to
access the server via the URL ?http://localhost/cgi-bin/zope.pcgi/?. This
should give you the same thing as ?http://localhost:8080/?.

Getting IIS to not override Zope?s error notification

IIS 4.0, by default, sends a custom 404 error message which overrides
Zope?s 404 error information. This behavior can create quite a few
problems, including authentication problems.

IIS 4.0?s error messages are implemented in the form of Custom Error
handlers, that return a file, or URL to a user when a specific error
occurs. This means, that when you forget to fill in an Id when you want to
create, say, a new SQL Method, Zope's clear error message is replaced by
IIS's totally irrelevant error message. Also, it completely breaks
authentication when the user uses IE5.0 to try to log into a secure area of
the server.

These Custom Error handlers are enabled by default. You need to disable
them in order for Zope?s clear error messages to be issued to the users. To
do that :

1.      Open the IIS website in the Management Console,
2.      Navigate to the folder where you put the Zope.pcgi file.
3.      Double-click on that file. A property page will appear.
4.      Select the 'Custom Errors' tab. Now, select every HTTP Error code
in the listbox that doesn't have type 'Default', and click on the 'Set to
Default' button for each one.
5.      Click OK.


Setting up Zope with IIS using FastCGI

[To come later]