Zope Installation Frequently Asked Questions
--------------------------------------------

  Installing Zope

    1. On certain Unix platforms (usually Solaris) I get a "checksum 
       error" untarring the Zope distribution. Whats the deal?

       Zope is built and distributed using GNU tar. Some vendor-supplied
       tar implementations have problems with long path names as they 
       appear in GNU tar created files. This is a problem that occurs in 
       a number of software distributions created using GNU tar, not just 
       Zope. We suggest that you install a GNU tar on your system to 
       avoid this problem (not just with Zope, but with other software 
       distributions as well).

    2. I am trying to build Zope on my BSD based system, but I
       keep getting "symbol not found" errors and the build
       scripts stop. What do I do?

       On some BSD based systems (BSDI, BSD/OS), you need to edit
       the Makefile.pre.in files in your Zope installation to add
       -rdynamic to the LDSHARED makefile variable. On some systems
       it may also be necessary to change the file named 'do.py'
       located in the 'inst' directory of your Zope installation,
       changing the line: do('make')  to: do('make -k').

    3. I am having trouble building Zope on my OpenBSD system.  I get
       some wierd compilation errors.

       Make sure you unpack Zope using GNU tar; you will not get any
       error messages with OpenBSD's standard tar, but your installation
       will be subtly broken due to problems with long path names.

    4. I am having trouble building Zope on a libc 5 Linux machine.
    
       Zope requires Python be built with glibc 2.x (libc 6) on Linux.

    5. I am trying to install Zope on a Windows NT/2000 machine, but
       I keep getting a dialog saying "corrupt installation detected".
       Is something wrong with the distribution file?

       No, to install Windows NT / 2000 you should be logged in with 
       "Administrator" privileges on the machine. If you are seeing
       the "corrupt installation detected" dialog, you probably don't
       have the required administrator privileges (your guess is as
       good as ours as to why you get that particular error message).


  Starting/Accessing your Zope installation

    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.

       Look in the error log for your web server for details of the error.


    2. I have installed Zope, and when I go to the URL in my web
       browser, I get a password prompt. Although I type in the correct
       username and password, I keep getting prompted. What is going on?

       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
       out of requests passed to cgi programs. If you keep getting password
       prompts that never accept your password, this means that your web
       server is not properly configured to pass authentication info on to
       Zope. See the doc/WEBVSERVER.txt file for information on correctly
       configuring your web server to pass authentication information.


    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.
       

    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 database loaded.  Depending on database file size, this might
       take a while. Packing your Zope database at regular intervals
       can reduce startup time.


    5. I have Zope with the Oracle Database adapter installed, and can't
       get it running. Why?

       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

       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
       I can't get access.  How do I fix it?

       Assuming you have write access to the directory where Zope is
       installed, you can create a temporary "emergency user" using
       the 'zpasswd.py' script::

           python zpasswd.py access

       Follow the prompts to enter a user name and password.
       'zpasswd.py' will write the file named 'access'.  Zope will
       look for this file the next time it starts.  After restarting,
       browse to Zope's management interface and use the name and
       password you entered.

       As the emergency user, you are allowed to create user folders
       and user accounts as well as adjust security settings but you
       are not allowed to create objects like DTML methods or folders.
       This is a safety precaution.

       See more details in the file SECURITY.TXT.

  Managing the Zope process

    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'.

    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'.

    3. Is it OK to use 'kill' to shutdown the process?

       It is best to shutdown the process using the Shutdown button in
       the Control Panel. Alternatively, the URL:

          'Control_Panel/manage_shutdown'

       will, with a suitable username and password, shutdown the
       application. If you need a non-interactive way to shutdown your
       application, e.g. from a script, then write a program that sends
       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.

    4. 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
       you need to migrate every single ZCatalog manually:

        - go to the ZMI 

        - click on your ZCatalog instance (or portal_catalog inside
          your CMF or Plone instance)

        - you will get an "AttributeError, _length"...don't panic

        - call the "manage_convertIndexes" method of the ZCatalog 
          (by replacing the "manage_main" part of the URL with
           "manage_convertIndexes")

        - depending on the size of your ZCatalog the migration may
          take a while

        - after the conversion a message will appear: "Indexes
          converted and reindexes"

        - Notice: **YOU SHOULD BACKUP YOUR var/Data.fs file before
          starting the migration**


  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.

       Occassionally you won't see the 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.
