FAQ updates merged from trunk.

doc/FAQ.txt

 Zope Installation Frequently Asked Questions
 --------------------------------------------
 
+
   Installing Zope
 
     1. On certain Unix platforms (usually Solaris) I get a "checksum 
@@ -52,12 +53,9 @@ Zope Installation Frequently Asked Questions
     1. After installing Zope, I go to the URL in my web browser
        but I get a "404 Not Found" or "Server Error" message
 
-       This message is coming from your web server, not Zope.
-       It usually means that your web server is misconfigured.
-       Ensure that the PCGI info file generated by the installation
-       procedure exists in a cgi-enabled directory, and that your
-       web server has any required aliases or configuration options
-       set to enable it to find this file and run it as a cgi program.
+       Is the URL really correct? Are you running Zope behind another
+       web server?  If so, this message is coming from your web server, 
+       not Zope.  It usually means that your web server is misconfigured.
 
        Look in the error log for your web server for details of the error.
 
@@ -66,6 +64,7 @@ Zope Installation Frequently Asked Questions
        browser, I get a password prompt. Although I type in the correct
        username and password, I keep getting prompted. What is going on?
 
+       Are you running another web server in front of Zope?
        Zope manages access control internally, but it relies on your
        web server software to relay any authentication information in
        web requests. Some web servers automatically filter this information
@@ -77,49 +76,27 @@ Zope Installation Frequently Asked Questions
 
 
     3. I have installed Zope, and when I go to the URL in my web
-       browser, I get a screen that says "Temporarily Unavailable".
-
-       Try the URL again - if you still get "Temporarily Unavailable",
-       this means that your PCGI resource file was unable to start
-       the Zope process. This usually means either an error in the
-       PCGI resource file, or a problem with your Zope installation
-       such as incorrect permissions on certain directories.
-
-       You should always run the install script to ensure that a
-       correct PCGI resource file is generated. If you have changed
-       this file by hand, ensure that all of the pathnames in the file
-       are valid and that there are no typos.
-
-       The install script should also ensure correct ownership and permissions
-       on files and directories in your Zope installation. The var
-       subdirectory of your installation and everything therein MUST be 
-       writable by the user which runs cgi scripts on your web server 
-       (usually nobody if you are using PCGI.)
-       
-       If you have ensured that the PCGI info file is correct and that all
-       permissions are correct, you can look in the /var/tmp directory of
-       your machine for files with names like "pcgi.110407". If PCGI fails
-       to start the Zope process, it will attempt to write a file
-       named pcgi.HHMMSS to /var/tmp containing information which may be
-       useful in determining the error.
-
-       On Windows NT platforms, check the event log under "Application Log"
-       for error information.
-
-       Additionally, if you receive a "Temporarily Unavailable", look at 
-       the document source for an HTML comment with error information.
-       
+       browser, I get a "Connection refused" error.
+
+       Probably this means that Zope has failed to start.  You should try 
+       to start Zope in the foreground and look for error messages.
+
+       On Linux / Unix / OSX, you can do this by giving the command
+       "./bin/runzope" or "./bin/zopectl fg"  in your zope instance
+       (they are equivalent).
+
+       On Windows, navigate to the Zope folder in your Start Menu and 
+       click on "Run Zope in Console". A console window with process 
+       startup information will be displayed.
+
+       If there are errors, the last error shown should explain
+       what went wrong.
+
 
     4. When I go to a URL for an application that isn't running, it
        takes quite a while to startup.  Why is that?
 
-       The *PCGI wrapper*, which is the executable run as a CGI script
-       on every request, has quite a bit of thinking to do.  First, it
-       has to see if the app is already running.  If not, it has to see 
-       if any other PCGI wrappers have already started the app.  It is
-       this latter part where some of the delay presents itself.
-
-       Next, the application itself has to get into memory and then get 
+       The application has to get into memory and then get 
        the database loaded.  Depending on database file size, this might
        take a while. Packing your Zope database at regular intervals
        can reduce startup time.
@@ -131,11 +108,12 @@ Zope Installation Frequently Asked Questions
        If you have Oracle installed, you need to ensure that the
        environment variable "ORACLE_HOME" is in the environment of
        the running application. You can do this by adding a line to 
-       your PCGI resource file such as: ORACLE_HOME=/usr/bin/oracle
+       the <environment> section of etc/zope.conf, such as:
+
+       <environment>
+           ORACLE_HOME /foo/bar/
+       </environment>
 
-       Any NAME=VALUE pairs appended to the PCGI resource file will
-       be added to the environment of the process when it is started
-       by PCGI.
 
     6. I have forgotten the only password used to access the site or
        I have modified the security settings in such a way that even
@@ -145,7 +123,7 @@ Zope Installation Frequently Asked Questions
        installed, you can create a temporary "emergency user" using
        the 'zpasswd.py' script::
 
-           python zpasswd.py access
+           python bin/zpasswd.py access
 
        Follow the prompts to enter a user name and password.
        'zpasswd.py' will write the file named 'access'.  Zope will
@@ -164,21 +142,22 @@ Zope Installation Frequently Asked Questions
 
     1. How do I find the application server in my process listing?
 
-       Whether running Zope with ZServer (yay) or straight PCGI (not
-       so yay), or there will be a .pid file in var with the pid of the
-       process.  For ZServer, the pid file is named 'z2.pid' (and it
-       contains two pids).  For PCGI, the file will be 'pcgi.pid'.
+       When running Zope, there will be a .pid file in var/Z2.pid
+       which contains two process IDs.
 
     2. If I have more than one Zope process running on the same
        machine, how do I tell them apart in "ps" listings?
 
        When running under ZServer, the Zope processes will show up in
-       the listings with 'z2.py'.  (You may need to do a long listing
-       to see it.)  PCGI mastered zopes will have 'pcgi-wrapper'.
+       the listings with 'run.py'.  (You may need to do a long listing
+       to see it.)  Look for the pids listed in var/Z2.pid. 
 
-    3. Is it OK to use 'kill' to shutdown the process?
+    3. Is it OK to use 'kill' to shut down the process?
 
-       It is best to shutdown the process using the Shutdown button in
+       If you started zope with the command "zopectl start", the command
+       "zopectl stop" will shut down Zope.
+
+       You can also shut down the process using the Shutdown button in
        the Control Panel. Alternatively, the URL:
 
           'Control_Panel/manage_shutdown'
@@ -189,12 +168,49 @@ Zope Installation Frequently Asked Questions
        a web request to that URL with the appropriate username and
        password.
 
-       If you must, you can shutdown the application by killing it.
-       The respective var/*.pid file will have the pids - for ZServer
-       (yay) it's var/z2.pid, for pcgi (not so yay), it's
-       var/pcgi.pid.
+       If you must, you can shut down the application by killing it.
+       The respective var/Z2.pid file will have the pids.
+
+
+  Upgrading from Earlier Versions of Zope
+
+    1. How can I upgrade to Zope 2.8?
+
+       The usual procedure when installing a new version of Zope is:
+
+       - Create a new instance (see doc/INSTALL.txt).
+
+       - Copy the var/Data.fs file from your old instance into your 
+         new instance's var/ directory. 
+
+         It is best to do this while the old instance is not running; 
+         alternatively, you can use repozo.py as described at 
+         http://www.zope.org/Wikis/ZODB/FileStorageBackup 
+         to make a live backup, then create a new Data.fs from that
+         backup in your new instance.
+
+         Keep your old Data.fs in the old instance as a backup.
+        
+       - Copy the Products and Extensions directories from your old 
+         instance into the new instance.
+
+         Leave the old instance directories intact as a backup.
+ 
+       - Update etc/zope.conf with any changes you made in your
+         old instance.  (Likewise for zeo.conf if you are using zeo.)
+
+       - Start the new instance. (Be sure the old instance is not running.)
 
-    4. After moving my old Data.fs to Zope 2.8 I get an 
+       - Update any ZCatalogs as described below. 
+
+       - Update any Python Scripts. This is not strictly necessary,
+         but it will make Zope restart somewhat faster.  Visit this URL 
+         in your browser:
+
+         http://.../manage_addProduct/PythonScripts/recompile
+
+
+    2. After moving my old Data.fs to Zope 2.8 I get an 
        "AttributeError, _length" when trying to use the ZCatalog?
 
        In Zope 2.8 we cleaned up the index implementations and therefore
@@ -224,19 +240,52 @@ Zope Installation Frequently Asked Questions
           converted and reindexed"
 
 
+    3. CMF doesn't work!
+
+        Check that you have a recent stable version of CMF.
+        As of Zope 2.8.0, you need at least CMF-1.4.8.  
+        CMF is available at http://www.zope.org/Products/CMF/
+
+
+    4. Plone doesn't work!
+
+        As of the release of Zope 2.8.0, Plone does not support
+        Zope 2.8 yet.  Check http://www.plone.org for updates.
+
+
   General
 
 
     1. My browser is giving a message, 'Sorry, an error occurred.'
        How do I find out what the real error is?
 
-       Step number one in these scenarios is to view the HTML source of 
-       the frame containing the error. In general, the *traceback* of
-       the error message is enclosed in an HTML comment. This
-       traceback explains the error message.
+       Step number one in these scenarios is to check the error log
+       on your server. The standard error page should provide you with a 
+       link directly to the log entry for that error.
+
+       If something has gone wrong with the standard error page itself, 
+       or if you are using a modified error page, this link may be 
+       missing. If this happens, you can visit /event_log/manage_main and 
+       browse the recent errors.
+
+       In general, error_log will show the *traceback* for errors.
+       This traceback explains the error message. 
 
-       Occassionally you won't see the error message. Rather, the HTML 
+       Occassionally you won't see any error message. Rather, the HTML 
        source will contain the last good HTML returned by the request
        before the error occurred. This is due to caching by the
        browser.  Clear your cache and view the HTML source again.
 
+
+    2. I'm using Python 2.4 and I'm having a problem ...
+
+       As of the release of Zope 2.8, Python 2.4 has not been approved for 
+       use with any version of Zope yet.  Please use Python 2.3. 
+
+       The correct version of Python should always be automatically detected
+       and used when you configure and install Zope. In general, you 
+       should let the configure script do its job and don't try to 
+       force an unsupported version of Python!
+
+
+