Zope Installation Frequently Asked Questions -------------------------------------------- Installing Zope 1. 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'). 2. 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. 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. 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), 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. What files are used by the object database? The state of the application is stored in files in the 'var' subdirectory inside the installation. There is currently one file: o Data.fs -- Primary database file Data.fs replaces the database file of prior versions, Data.bbb. To convert an existing Data.bbb file to the new format, see doc/ZODB.txt. Other files in the 'var' directory are associated with each process and are only temporary. 4. 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. General 1. My browser is giving a message of 'Sorry, an error occurred.' How do I find out the error? 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.