zope install and start
http://www.plope.com/Books/2_7Edition/InstallingZope.stx
* Installing and Starting Zope
o Downloading Zope
o Installing Zope
+ Installing Zope for Windows With Binaries from Zope.org
+ Compiling and Installing Zope from Source Code
o Starting Zope
o Using Zope With An Existing Webserver
o Starting Zope On Windows
o Starting Zope on UNIX
+ Starting Zope As The Root User
o Your Zope Installation
o Logging In
o Controlling the Zope Process With the Control Panel
o Controlling the Zope Process From the Command Line
o Troubleshooting and Caveats
+ Running zopectl returns with an OSError
+ Browser cannot connect to port 8080
+ Forgot administrative password
o Customizing your Zope instance
# Server stanzas and port-base
# The debug-mode directive
# Additional products directories
# Switch the User the Zope process runs as: effective-user
# Configuring the Session machinery
# Logging
o When All Else Fails
Installing and Starting Zope
By the end of this chapter you should be able to install and start Zope. It is fairly easy to install Zope on most platforms, and it should typically take you no longer than ten minutes.
Downloading Zope
There are typically two types of Zope releases: a "stable" release and a "development" release. If you are new to Zope, you almost certainly want to use the "stable" Zope release.
You may download Zope from the Zope.org web site. The most recent stable and development versions are always available from the Download area of the Zope.org website.
Zope comes as a "binary" release for the Windows platform, and in source format for Unix-like operating systems. Zope may be compiled on almost any Unix-like operating system. Zope has reportedly been successfully compiled on Linux, FreeBSD, NetBSD, OpenBSD, Mac OS X, HPUX, IRIX, DEC OFS/1, and even Cygwin (the UNIX emulation platform for Windows). As a general rule of thumb, if Python is available for your operating system, and you have a C compiler and associated development utilities, then you can probably compile Zope. A notable exception is Mac OS 7/8/9. Zope does not run at all on these platforms.
Various binary Zope packages exist that are not distributed by Zope Corporation, but instead are distributed by third parties. Provided here is a list of URLs to these below for convenience's sake. These packages are not directly supported by Zope Corporation, although Zope Corporation encourages alternate binary distributions for unsupported platforms by third parties. Not all versions of Zope are available for all platforms.
SPVI's Mac OS X binary distro
Marcus Schopens Zope packages for Linux
FreeBSD Zope port
Debian Linux Zope package
Gentoo Zope ebuild
Some other Linux distributions, eg. SUSE, also include Zope with their products. Check your vendors documentation to find out more.
Installing Zope
Zope requires different installation steps depending on your operating system platform. The sections below detail installing the binary version of Zope on Windows on Intel platforms, and a source installation on Linux.
Installing Zope for Windows With Binaries from Zope.org
The "Win32" version of Zope works under Windows 95, Windows 98, Windows ME, Windows NT, Windows 2000, Windows XP and Windows Server 2003. Zope for Windows comes as a self-installing .exe file. To install Zope, first, download the Win32 executable installer from the Download area on Zope.org. It is typically named something like "Zope-2.X.X-win32-x86.exe" where the "X"'s refer to the current Zope version number.
[myimg]upload/download-zope.png[/myimg]
Figure 2-1 Current stable Windows Zope Release
Download the current stable release installer for Windows from Zope.org using your web browser. Place the file in a temporary directory on your hard disk or on your Desktop. Once the installer file has been downloaded, navigate to the folder in which you downloaded the file to, and double-click on the file's icon. The installer then begins to walk you through the installation process.
[myimg]upload/installer-package-icon.png[/myimg]
Figure 2-2 Zope installer
[myimg]upload/installer-first-screen.png[/myimg]
Figure 2-3 Beginning the installer
Click Next. The installer asks for an installation path. The default is usually acceptable, though you are of course free to choose another path. Then click Next. You then can choose which components to install.
[myimg]upload/component-selection.png[/myimg]
Figure 2-4 Select components
You should select "Full installation" unless you know what you are doing. On the next screen, you may customize the entry placed in your Start Menu folder. Click Next again. The installer now asks you wether you would like to run Zope as a service, unless you are running Windows 98 or ME, where services are not available. If you are just running Zope for personal use, don't bother running it as a service.
[myimg]upload/start-as-service.png[/myimg]
Figure 2-5 Server Options
Upon clicking Next, the installer takes you to the "Instance Setup" Screen.
[myimg]upload/instance-path.png[/myimg]
Figure 2-6 Instance Setup
You can have more than one Zope running on your PC, but each has to have its own Instance Home. The Instance Home is the path you have to specify here. This is the path where Zope later will place its database files. Make sure that you have enough disk space left on the specified drive and that you can make backups easily.
The Next screen asks you for a password for an initial administrative account. You use this account to log in for the first time and create more users. Note that the installer does not ask you to verify your password -- be careful not to mis-type your password.
[myimg]upload/instance-passwd.png[/myimg]
Figure 2-7 Administrative password
Click Next after entering a password. The installer presents an overview, commence installation by clicking Install. After a few moments, the Zope installer should present you with a "Completion" screen.
[myimg]upload/installer-complete.png[/myimg]
Figure 2-8 Installation completion
Let the installer start Zope for you, or start Zope manually by navigating to the Zope folder in the Start Menu and selecting "Run Zope in Console". See below in the section entitled "Starting Zope".
Compiling and Installing Zope from Source Code
If binaries aren't available for your platform, chances are good that you will be able to compile Zope from its source code. To do this, however, you first must:
* ensure you have a "C" compiler on your system (GNU gcc is preferred)
* ensure you have a recent "make" on your system (GNU make is preferred)
* install the Python language on your system from source (or install a binary package including development headers)
Zope is written primarily in the Python language, and Zope requires Python to be able to run at all. Though binary versions of Zope ship with a recent Python, the source Zope distribution does not. Although we try to use the most recent Python for Zope, often the latest Python version is more recent than the version we "officially" support for Zope. For the most recent information on which version of Python you need to compile Zope with, see the release notes on the Web page for each version. Zope 2.7 requires Python 2.3.2 or later. Zope versions 2.5 and 2.6 require a Python 2.1 version equal to or greater than 2.1.3.
You can obtain instructions for downloading, compiling and installing Python from source at the Python.org web site. Some Linux distributions ship with a preinstalled Python 2.3, but you need to be careful when attempting to use a vendor-installed Python to compile Zope. Some of these vendor-supplied Python distributions do not ship the necessary Python development files needed to compile Zope from source. Sometimes these development files are included in a separate "python-devel" package that you may install and use, but sometimes they are not. The author has used the binary packages shipping with Debian with success, but in general it is advisable that you compile and install Python from source if you wish to compile and install Zope from source.
After downloading, compiling, and installing Python from source, download the current Zope source distribution. See the Zope.org Downloads area for the latest Zope source release.
Download the source to your home directory. After you have downloaded the source tarball, cd to your home directory and unpack it with something similar to:
$ gunzip -c Zope-2.7.0.tgz | tar xvf -
Zope now uses the conventional UNIX build sequence configure, make, make install.
To configure Zope, cd to the Zope directory and issue the configure command:
$ cd Zope-2.7.0
$ ./configure --prefix=/where/to/install/zope
Replace /where/to/install/zope above with an appropriate path, for instance ~/myzope/zope2.7. This path is referred to as the ZOPE_HOME. If you want to install Zope in a system directory instead of your user home, replace ~/myzope/zope2.7 with an appropriate path, eg. /usr/local/zope2.7 and make sure you have suitable privileges for installing and starting Zope.
If the configure script is unable to find your Python installation, it will report an error not unlike this one:
$ ./configure --prefix=~/myzope/zope2.7
Configuring Zope installation
Testing for an acceptable Python interpreter...
No suitable Python version found. You should install
Python version 2.3.3 before continuing. Versions
2.3.2 2.3.1 2.3 2.2.3 2.2.2 also work, but not as optimally.
In this case, you have to point it to your Python interpreter -- which you should have installed either from a binary package or compiled yourself, see above.
Use the --with-python option to the configure script, eg. for a python living under /usr/local :
$ ./configure --prefix=~/myzope/zope2.7 \\
--with-python=/usr/local/bin/python
Replace /usr/local/bin/python with the path to your Python executable.
Zope is now ready to be built. From within the source directory, issue:
$ make
[ lots of output snipped ]
Zope built. Next, do 'make install' (or 'make instance'
to run a Zope instance directly from the build directory).
You are now ready to install Zope. To do this, you will have to execute make install :
$ make install
[ lots of output snipped ]
Zope binaries installed successfully.
Now run '~/myzope/zope2.7/bin/mkzopeinstance.py'
With the Zope binaries installed, you are now ready to install a Zope instance. A Zope instance holds configuration and runtime data for a single Zope server process. This helps to keep your own or third-party software separate from the main Zope source.
We will assume you want to install a Zope instance in the directory ~/myzope/instance. To create a Zope instance, run the following command:
$ ~/myzope/zope2.7/bin/mkzopeinstance.py
You will need to provide the following values:
* The directory where your instance should be located -- the INSTANCE_HOME. The instance home will hold your database files, log files, the "Extensions" and "Products" directories, configuration files, and scripts to start and stop the instance. For our example, we assume the instance home to be located at ~/myzope/instance
* Username and Password for an initial Zope user. You will log in with this username and password to create your own Zope users. To change the username or password for your initial Zope user, run:
$ cd ~/myzope/instance
$ ~/myzope/zope2.7/bin/zpasswd.py inituser
You will have to provide the username and password you wish to set; optionally, you can specify the hashing method and an additional domain restriction.
Zope installation is now complete. Read on to see how to start your brand new Zope.
Starting Zope
Zope is managed via a web browser, and Zope contains its own web server (named "ZServer"). A successful Zope startup implies that its web server starts, allowing you to access the Zope management interface via your web browser. You can access Zope's management interface from the same machine on which Zope runs, or you can access it from a remote machine that is connected to the same network as your Zope server.
Zope's ZServer will "listen" for HTTP (web browser, or Hypertext Transfer Protocol) requests on TCP port 8080. If your Zope instance fails to start, make sure you don't have another application running which is already using TCP port 8080.
Zope also has the capability to listen on other TCP ports. Zope supports separate TCP ports for FTP (File Transfer Protocol), "monitor" (internal debugging), WebDAV (Web Distributed Authoring and Versioning), and ICP (Internet Cache Protocol) access. If you see messages which indicate that Zope is listening on ports other than the default 8080 HTTP, don't panic, it's likely normal.
Using Zope With An Existing Webserver
If you wish, you can configure your existing web server to serve Zope content. Zope interfaces with Microsoft IIS, Apache, and other popular webservers.
The
Virtual Hosting Services chapter of this book provides rudimentary setup information for configuring Zope behind Apache. However, configuring Zope for use behind an existing webserver can be a complicated task, and there is more than one way to get it done. In the interest of completeness, here are some additional resources which should get you started:
* Apache: see the excellent DevShed article entitled Using Zope With Apache .
* IIS: see brianh's HowTo on using IIS with Zope. Also of interest may be the WEBSERVER.txt file in your Zope installation's doc directory, and hiperlogica's Connecting IIS to Zope article.
If you are just "getting started" with Zope, note that it is not necessary to configure Apache or IIS (or any other webserver) to serve your Zope pages, as Zope comes with its own webserver. You typically only need to configure your existing webserver if you want to use it to serve Zope pages in a production environment.
Starting Zope On Windows
If you installed Zope to "run manually" (as opposed to installing Zope as a "service"), 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 you chose to run Zope as a "service" on Windows NT/2000/XP, you can start Zope via the standard Windows "Services" control panel application. A Zope started as a service writes events to the standard Windows Event Log; you can keep track of when your service starts and stops by reviewing your system's Event Log. A Zope instance which has been installed as a "service" can also be run manually by invoking the Run Zope in Console menu entry as described above. Take care though that you either can run Zope manually or as a service at the same time, so make sure you stop the Zope service if you want to invoke Zope manually.
Starting Zope on UNIX
Important note: If you installed Zope from an RPM or a another "vendor distribution" instead of installing a Zope Corporation-distributed source release, the instructions below may be not be applicable. Under these circumstances, please read the documentation supplied by the vendor to determine how to start your Zope instance instead of relying on the instructions below.
To start your Zope instance (which we assumed to live in ~/myzope/instance) issue:
$ ~/myzope/instance/bin/zopectl start
This will start the instance in the background. Alternatively you can start it in the foreground by issuing:
$ ~/myzope/instance/bin/zopectl fg
Run the zopectl script with a parameter of help to get a list of additional commands:
$ ~/myzope/instance/bin/zopectl help
Starting Zope As The Root User
ZServer (Zope's server) supports setuid() on POSIX systems in order to be able to listen on low ports such as 21 (FTP) and 80 (HTTP) but drop root privileges when running; on most POSIX systems only the root user can do this. Versions of Zope prior to 2.6 had less robust versions of this support. Several problems were corrected for the 2.6 release.
The most important thing to remember about this support is that you don't have to start ZServer as root unless you want to listen for requests on "low" ports. In fact, if you don't have this need, you are much better off just starting ZServer as a user account dedicated to running Zope. nobody is not a good idea for this user account, because if any other daemon on a system that ran as nobody was compromised, this would have opened up your Zope object data to compromise.
If you do need to have ZServer listening on low ports, you will need to start zopectl as the root user, and also specify what user ZServer should setuid() to. Do this by setting the effective-user parameter in your Zope instances configuration file, residing in $INSTANCE_HOME/etc/zope.conf and make sure the log and database files are writeable by this user.
Your Zope Installation
To use and manage Zope, you will need a web browser. Zope's management interface is written entirely in HTML, therefore any browser that understands modern HTML allows you to manage a Zope installation. Mozilla, and any 3.0+ version of Microsoft Internet Explorer or Netscape Navigator will do. Other browsers that are known to work with Zope include Opera, Galeon, Konqueror, OmniWeb, Lynx, and W3M.
Start a web browser on the same machine on which you installed Zope and visit the URL
http://localhost:8080/ . If your Zope is properly installed and you're visiting the correct URL, you will be presented with the Zope "QuickStart" screen.
[myimg]upload/quickstart.png[/myimg]
Figure 2-8 Zope QuickStart
If you see this screen, congratulations! You've installed Zope successfully. If you don't, see the Troubleshooting section below.
Logging In
To do anything remotely interesting with Zope, you need to use its "management interface", also known as the ZMI. Zope is completely web-manageable. To log into the Zope management interface, use your web browser to navigate to Zope's management URL. Assuming you have Zope installed on the same machine from which you are running your web browser, the Zope management URL will be http://localhost:8080/manage.
Successful contact with Zope using this URL will result in an authentication dialog. In this dialog enter the "initial" username and password you chose when you installed Zope. You will be presented with the Zope Management Interface (ZMI).
[myimg]upload/zmi.png[/myimg]
Figure 2-9 The Zope Management Interface.
If you do not see an authentication dialog and the Zope Management interface, refer to the Troubleshooting section of this chapter.
Controlling the Zope Process With the Control Panel
When you are using the ZMI, you can use the Zope Control Panel to control the Zope process. Find and click the Control_Panel object in ZMI.
The Control Panel
Figure 2-10 The Control Panel
The Control Panel displays information about your Zope, such as the Zope version you are running, the Python version that Zope is using, the system platform, the INSTANCE_HOME, the ZOPE_HOME, Zope's process id, the Network Services that have been started, how long Zope has been running for, and other installation specifics. Several buttons and links will also be shown.
If you are running Zope on UNIX or as a service on Windows, you will see a button in the Control Panel named Restart. If you click the Restart button, Zope will shut down and then immediately start up again. It may take Zope a few seconds to come back up and start handling requests. You needn't shut your web browser down and restart it to resume using Zope after pressing Restart, just wait for the Control Panel display to reappear.
To shut Zope down from the ZMI, click the Shutdown button. Shutting Zope down will cause the server to stop handling requests and exit. You will have to manually start Zope to resume using it. Shut Zope down only if you are finished using it and you have the ability to access the server on which Zope is running, so that you can manually restart it later.
Controlling the Zope Process From the Command Line
To stop a manually-run Zope on Windows press "Ctrl-C" while the console window under which Zope is running is selected. To stop a Zope on Windows that was run as a service, find the service with the name you assigned to your Zope installed in the Services Control Panel application and stop the service.
To stop Zope on UNIX, do one of the following:
* press "Ctrl-C" in the terminal window from which you started Zope if you started it in the foreground
* if you started Zope in the background, use the zopectl script:
$ ~/myzope/instance/bin/zopectl stop
* use the UNIX "kill" command against the process id in the "var/Z2.pid" file inside of your Zope instance directory:
$ kill `cat var/Z2.pid`
Troubleshooting and Caveats
Running zopectl returns with an OSError
When running Zope on a 2.6.x Linux kernel, Solaris or MaC OSX, zopectl returns with OSError: [Errno 10] No child processes. This is due to a bug in Zope 2.7.0. You have the following options:
* Install a patch currently in CVS. See http://zope.org/Collectors/Zope/1235 for the collector log and a small patch. The patch file is named zdctl.diff. Download it to a temporary directory, eg. /tmp. Then change to the directory $ZOPE_HOME/lib/python/zdaemon (in our previous examples, this would be ~/myzope/zope2.7/lib/python/zdaemon) and run the patch command: patch < /tmp/zdctl.diff. The patch program should respond with an output like patching file zdctl.py.
* Downgrade to a 2.4.x kernel if you are running Linux.
* Work around this issue by placing Zope in the background manually with:
$ nohup ~/myzope/instance/bin/runzope &
Note though that your Zope instance will not be automatically restarted by zdaemon this way; you probably should not use this workaround on a production server.
Browser cannot connect to port 8080
If your browser fails to connect with anything on TCP port 8080, your Zope may be running on a nonstandard TCP port (for example, some versions of Debian Linux ship with Zope's TCP port as 9673). To find out exactly which URL to use, look at the logging information Zope prints as it starts up when started in the foreground, ie. when started with ./runzope or ./zopectl fg. For example:
------
2004-04-21T21:48:27 INFO(0) ZServer HTTP server started at Wed Apr 21 21:48:27 2004
Hostname: arod
Port: 9673
------
2004-04-21T21:48:27 INFO(0) ZServer FTP server started at Wed Apr 21 21:48:27 2004
Hostname: arod
Port: 8021
...
The first log entry indicates that Zope's web server is listening on port 9673 on host arod. This means that the management URL is http://arod:9673/manage.
As mentioned above, Zope only prints to the console if started in the foreground, with ./runzope or runzope.bat, respectively. The same information can be found in the log/event.log file in your INSTANCE_HOME directory.
Certain versions of Microsoft Internet Explorer 5.0.1 and 5.5 have issues with the Zope management interface which manifest themselves as an inability to properly log in. If you have troubles logging in with IE 5.0.1 or IE 5.5, try a different browser or upgrade IE 6.
Forgot administrative password
If you forget or lose the initial user name and password, shut Zope down and change the initial user password with the zpasswd.py script and restart Zope. See the chapter entitled Users and Security for more information about configuring the initial user account.
Customizing your Zope instance
As of Zope 2.7.0, configuration no longer is done with a mix of environment variables and command line options. Instead, there is a directory etc in your instance home, which contains a zope.conf file where numerous configuration directives can be specified. This scheme greatly enhances manageability and configurability for Zope 2.7.x
The
zope.conf file has extensive inline documentation which we will not reproduce here. We will give an overview and some additional hints for the most widely used directives though.
Server stanzas and port-base
The port-base directive together with the stanzas for the individual servers determine the ports those servers listen on. The stanzas are formed with XML-like constructs:
<http-server>
# valid keys are "address" and "force-connection-close"
address 8080
</http-server>
<ftp-server>
...
</ftp-server>
<webdav-source-server>
...
</webdav-source-server>
The address directive determines the port the respective server listens on. The HTTP Server in this example listens on port 8080.
The port-base directive comes in handy if you want to run several Zope instances on one machine. port-base specifys an offset to the port all servers listens on. Let us assume our HTTP Servers address directive is set to 8080 like in our example above, and port-base is specified as 1000. The actual port the HTTP Server will listen on will be 9080. Assuming the FTP Servers address directive is set to 8021, the FTP Server will then listen on port 9021, and so on.
The debug-mode directive
This directive is a switch, specified as either on or off. When set to on (the default), Zope runs in debug mode. This causes Zope to reload Filesystem-based templates in real time and several other settings suitable for development. You should set this directive to off in a productions environment however.
Additional products directories
One of the most useful directive in the authors opinion. You can specify additional Products directories here, ie. places where Zope looks for (possibly third-party) add-on Zope Products. Two directories come to mind: one for commonly used third-party Products like CookieCrumbler or CMF and Plone packages, which I like to keep in /usr/local/zopeproducts (any directory will do, of course). The benefit is better separation of core Zope Products and third-party Add-Ons. The other directory could be of interest for Zope Product developers, which are able to specify a probably version-controlled development directory with this directive.
Switch the User the Zope process runs as: effective-user
This directive causes Zope to setuid(2) to the specified user when run as root on a Unix system. This benefits security a lot, since a compromised Zope cannot as easily damage a whole system. One motivation for running Zope as root in the first place is to be able to bind to privileged ports (ports with numbers below 1024)
Configuring the Session machinery
Use the maximum-number-of-session-objects directive to limit the number of session objects. This value defaults to 1000 objects; 0 means unlimited.
session-timeout-minutes sets the Session timeout in minutes. The default is 20min.
Logging
Three log facilities are provided: access logging, event logging, and trace logging. Access logging logs individual HTTP Requests in a common format, by default to the file log/Z2.log in your instance home. Event logging logs Zope events, for example start/stop information or debugging messages. The Trace logger logs detailed Zope debugging information.
Each log message has an associated severity level, ranging from CRITICAL, ERROR, WARN, INFO to DEBUG and ALL. You can specify a filter for log messages with the level directive inside a logger stanza. Set the level to ALL to get all log messages, or to ERROR or CRITICAL to see only the most serious messages.
The default is to write the messages to a log file; you can however arrange for log messages to be mailed to you or to go to syslog(3) (on Unix) or the NT event log (on MS Windows)
For further documentation, see the inline comments in zope.conf
When All Else Fails
If there's a problem with your installation that you just cannot seem to solve, do not despair. You have many places to turn for help, including the Zope maillists and the #zope IRC channel.
If you are new to open source software, please realize that, for the most part, participants in the various "free" Zope support forums are volunteers. Though they are typically friendly and helpful, they are not obligated to answer your questions. Therefore, it's in your own self-interest to exercise your best manners in these forums in order to get your problem resolved quickly.
The most reliable way to get installation help is to send a message to the general Zope maillist detailing your installation problem. For more information on the available Zope mailing lists, see the Resources section of Zope.org. Typically someone on the "[email protected]" list will be willing to help you solve the problem.
For even more immediate help, you may choose to visit the #zope channel on the OpenProjects IRC (Internet Relay Chat) network. See the OpenProjects website for more information on how to connect to the OpenProjects IRC network.
If you are truly desperate and under a time constraint that prohibits you from utilizing "free" support channels, Zope Corporation provides for-fee service contracts which you can use for Zope installation help. See Zope.com for more information about Zope Corporation service contracts.
* Installing and Starting Zope
o Downloading Zope
o Installing Zope
+ Installing Zope for Windows With Binaries from Zope.org
+ Compiling and Installing Zope from Source Code
o Starting Zope
o Using Zope With An Existing Webserver
o Starting Zope On Windows
o Starting Zope on UNIX
+ Starting Zope As The Root User
o Your Zope Installation
o Logging In
o Controlling the Zope Process With the Control Panel
o Controlling the Zope Process From the Command Line
o Troubleshooting and Caveats
+ Running zopectl returns with an OSError
+ Browser cannot connect to port 8080
+ Forgot administrative password
o Customizing your Zope instance
# Server stanzas and port-base
# The debug-mode directive
# Additional products directories
# Switch the User the Zope process runs as: effective-user
# Configuring the Session machinery
# Logging
o When All Else Fails
Installing and Starting Zope
By the end of this chapter you should be able to install and start Zope. It is fairly easy to install Zope on most platforms, and it should typically take you no longer than ten minutes.
Downloading Zope
There are typically two types of Zope releases: a "stable" release and a "development" release. If you are new to Zope, you almost certainly want to use the "stable" Zope release.
You may download Zope from the Zope.org web site. The most recent stable and development versions are always available from the Download area of the Zope.org website.
Zope comes as a "binary" release for the Windows platform, and in source format for Unix-like operating systems. Zope may be compiled on almost any Unix-like operating system. Zope has reportedly been successfully compiled on Linux, FreeBSD, NetBSD, OpenBSD, Mac OS X, HPUX, IRIX, DEC OFS/1, and even Cygwin (the UNIX emulation platform for Windows). As a general rule of thumb, if Python is available for your operating system, and you have a C compiler and associated development utilities, then you can probably compile Zope. A notable exception is Mac OS 7/8/9. Zope does not run at all on these platforms.
Various binary Zope packages exist that are not distributed by Zope Corporation, but instead are distributed by third parties. Provided here is a list of URLs to these below for convenience's sake. These packages are not directly supported by Zope Corporation, although Zope Corporation encourages alternate binary distributions for unsupported platforms by third parties. Not all versions of Zope are available for all platforms.
SPVI's Mac OS X binary distro
Marcus Schopens Zope packages for Linux
FreeBSD Zope port
Debian Linux Zope package
Gentoo Zope ebuild
Some other Linux distributions, eg. SUSE, also include Zope with their products. Check your vendors documentation to find out more.
Installing Zope
Zope requires different installation steps depending on your operating system platform. The sections below detail installing the binary version of Zope on Windows on Intel platforms, and a source installation on Linux.
Installing Zope for Windows With Binaries from Zope.org
The "Win32" version of Zope works under Windows 95, Windows 98, Windows ME, Windows NT, Windows 2000, Windows XP and Windows Server 2003. Zope for Windows comes as a self-installing .exe file. To install Zope, first, download the Win32 executable installer from the Download area on Zope.org. It is typically named something like "Zope-2.X.X-win32-x86.exe" where the "X"'s refer to the current Zope version number.
[myimg]upload/download-zope.png[/myimg]
Figure 2-1 Current stable Windows Zope Release
Download the current stable release installer for Windows from Zope.org using your web browser. Place the file in a temporary directory on your hard disk or on your Desktop. Once the installer file has been downloaded, navigate to the folder in which you downloaded the file to, and double-click on the file's icon. The installer then begins to walk you through the installation process.
[myimg]upload/installer-package-icon.png[/myimg]
Figure 2-2 Zope installer
[myimg]upload/installer-first-screen.png[/myimg]
Figure 2-3 Beginning the installer
Click Next. The installer asks for an installation path. The default is usually acceptable, though you are of course free to choose another path. Then click Next. You then can choose which components to install.
[myimg]upload/component-selection.png[/myimg]
Figure 2-4 Select components
You should select "Full installation" unless you know what you are doing. On the next screen, you may customize the entry placed in your Start Menu folder. Click Next again. The installer now asks you wether you would like to run Zope as a service, unless you are running Windows 98 or ME, where services are not available. If you are just running Zope for personal use, don't bother running it as a service.
[myimg]upload/start-as-service.png[/myimg]
Figure 2-5 Server Options
Upon clicking Next, the installer takes you to the "Instance Setup" Screen.
[myimg]upload/instance-path.png[/myimg]
Figure 2-6 Instance Setup
You can have more than one Zope running on your PC, but each has to have its own Instance Home. The Instance Home is the path you have to specify here. This is the path where Zope later will place its database files. Make sure that you have enough disk space left on the specified drive and that you can make backups easily.
The Next screen asks you for a password for an initial administrative account. You use this account to log in for the first time and create more users. Note that the installer does not ask you to verify your password -- be careful not to mis-type your password.
[myimg]upload/instance-passwd.png[/myimg]
Figure 2-7 Administrative password
Click Next after entering a password. The installer presents an overview, commence installation by clicking Install. After a few moments, the Zope installer should present you with a "Completion" screen.
[myimg]upload/installer-complete.png[/myimg]
Figure 2-8 Installation completion
Let the installer start Zope for you, or start Zope manually by navigating to the Zope folder in the Start Menu and selecting "Run Zope in Console". See below in the section entitled "Starting Zope".
Compiling and Installing Zope from Source Code
If binaries aren't available for your platform, chances are good that you will be able to compile Zope from its source code. To do this, however, you first must:
* ensure you have a "C" compiler on your system (GNU gcc is preferred)
* ensure you have a recent "make" on your system (GNU make is preferred)
* install the Python language on your system from source (or install a binary package including development headers)
Zope is written primarily in the Python language, and Zope requires Python to be able to run at all. Though binary versions of Zope ship with a recent Python, the source Zope distribution does not. Although we try to use the most recent Python for Zope, often the latest Python version is more recent than the version we "officially" support for Zope. For the most recent information on which version of Python you need to compile Zope with, see the release notes on the Web page for each version. Zope 2.7 requires Python 2.3.2 or later. Zope versions 2.5 and 2.6 require a Python 2.1 version equal to or greater than 2.1.3.
You can obtain instructions for downloading, compiling and installing Python from source at the Python.org web site. Some Linux distributions ship with a preinstalled Python 2.3, but you need to be careful when attempting to use a vendor-installed Python to compile Zope. Some of these vendor-supplied Python distributions do not ship the necessary Python development files needed to compile Zope from source. Sometimes these development files are included in a separate "python-devel" package that you may install and use, but sometimes they are not. The author has used the binary packages shipping with Debian with success, but in general it is advisable that you compile and install Python from source if you wish to compile and install Zope from source.
After downloading, compiling, and installing Python from source, download the current Zope source distribution. See the Zope.org Downloads area for the latest Zope source release.
Download the source to your home directory. After you have downloaded the source tarball, cd to your home directory and unpack it with something similar to:
$ gunzip -c Zope-2.7.0.tgz | tar xvf -
Zope now uses the conventional UNIX build sequence configure, make, make install.
To configure Zope, cd to the Zope directory and issue the configure command:
$ cd Zope-2.7.0
$ ./configure --prefix=/where/to/install/zope
Replace /where/to/install/zope above with an appropriate path, for instance ~/myzope/zope2.7. This path is referred to as the ZOPE_HOME. If you want to install Zope in a system directory instead of your user home, replace ~/myzope/zope2.7 with an appropriate path, eg. /usr/local/zope2.7 and make sure you have suitable privileges for installing and starting Zope.
If the configure script is unable to find your Python installation, it will report an error not unlike this one:
$ ./configure --prefix=~/myzope/zope2.7
Configuring Zope installation
Testing for an acceptable Python interpreter...
No suitable Python version found. You should install
Python version 2.3.3 before continuing. Versions
2.3.2 2.3.1 2.3 2.2.3 2.2.2 also work, but not as optimally.
In this case, you have to point it to your Python interpreter -- which you should have installed either from a binary package or compiled yourself, see above.
Use the --with-python option to the configure script, eg. for a python living under /usr/local :
$ ./configure --prefix=~/myzope/zope2.7 \\
--with-python=/usr/local/bin/python
Replace /usr/local/bin/python with the path to your Python executable.
Zope is now ready to be built. From within the source directory, issue:
$ make
[ lots of output snipped ]
Zope built. Next, do 'make install' (or 'make instance'
to run a Zope instance directly from the build directory).
You are now ready to install Zope. To do this, you will have to execute make install :
$ make install
[ lots of output snipped ]
Zope binaries installed successfully.
Now run '~/myzope/zope2.7/bin/mkzopeinstance.py'
With the Zope binaries installed, you are now ready to install a Zope instance. A Zope instance holds configuration and runtime data for a single Zope server process. This helps to keep your own or third-party software separate from the main Zope source.
We will assume you want to install a Zope instance in the directory ~/myzope/instance. To create a Zope instance, run the following command:
$ ~/myzope/zope2.7/bin/mkzopeinstance.py
You will need to provide the following values:
* The directory where your instance should be located -- the INSTANCE_HOME. The instance home will hold your database files, log files, the "Extensions" and "Products" directories, configuration files, and scripts to start and stop the instance. For our example, we assume the instance home to be located at ~/myzope/instance
* Username and Password for an initial Zope user. You will log in with this username and password to create your own Zope users. To change the username or password for your initial Zope user, run:
$ cd ~/myzope/instance
$ ~/myzope/zope2.7/bin/zpasswd.py inituser
You will have to provide the username and password you wish to set; optionally, you can specify the hashing method and an additional domain restriction.
Zope installation is now complete. Read on to see how to start your brand new Zope.
Starting Zope
Zope is managed via a web browser, and Zope contains its own web server (named "ZServer"). A successful Zope startup implies that its web server starts, allowing you to access the Zope management interface via your web browser. You can access Zope's management interface from the same machine on which Zope runs, or you can access it from a remote machine that is connected to the same network as your Zope server.
Zope's ZServer will "listen" for HTTP (web browser, or Hypertext Transfer Protocol) requests on TCP port 8080. If your Zope instance fails to start, make sure you don't have another application running which is already using TCP port 8080.
Zope also has the capability to listen on other TCP ports. Zope supports separate TCP ports for FTP (File Transfer Protocol), "monitor" (internal debugging), WebDAV (Web Distributed Authoring and Versioning), and ICP (Internet Cache Protocol) access. If you see messages which indicate that Zope is listening on ports other than the default 8080 HTTP, don't panic, it's likely normal.
Using Zope With An Existing Webserver
If you wish, you can configure your existing web server to serve Zope content. Zope interfaces with Microsoft IIS, Apache, and other popular webservers.
The
Virtual Hosting Services chapter of this book provides rudimentary setup information for configuring Zope behind Apache. However, configuring Zope for use behind an existing webserver can be a complicated task, and there is more than one way to get it done. In the interest of completeness, here are some additional resources which should get you started:
* Apache: see the excellent DevShed article entitled Using Zope With Apache .
* IIS: see brianh's HowTo on using IIS with Zope. Also of interest may be the WEBSERVER.txt file in your Zope installation's doc directory, and hiperlogica's Connecting IIS to Zope article.
If you are just "getting started" with Zope, note that it is not necessary to configure Apache or IIS (or any other webserver) to serve your Zope pages, as Zope comes with its own webserver. You typically only need to configure your existing webserver if you want to use it to serve Zope pages in a production environment.
Starting Zope On Windows
If you installed Zope to "run manually" (as opposed to installing Zope as a "service"), 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 you chose to run Zope as a "service" on Windows NT/2000/XP, you can start Zope via the standard Windows "Services" control panel application. A Zope started as a service writes events to the standard Windows Event Log; you can keep track of when your service starts and stops by reviewing your system's Event Log. A Zope instance which has been installed as a "service" can also be run manually by invoking the Run Zope in Console menu entry as described above. Take care though that you either can run Zope manually or as a service at the same time, so make sure you stop the Zope service if you want to invoke Zope manually.
Starting Zope on UNIX
Important note: If you installed Zope from an RPM or a another "vendor distribution" instead of installing a Zope Corporation-distributed source release, the instructions below may be not be applicable. Under these circumstances, please read the documentation supplied by the vendor to determine how to start your Zope instance instead of relying on the instructions below.
To start your Zope instance (which we assumed to live in ~/myzope/instance) issue:
$ ~/myzope/instance/bin/zopectl start
This will start the instance in the background. Alternatively you can start it in the foreground by issuing:
$ ~/myzope/instance/bin/zopectl fg
Run the zopectl script with a parameter of help to get a list of additional commands:
$ ~/myzope/instance/bin/zopectl help
Starting Zope As The Root User
ZServer (Zope's server) supports setuid() on POSIX systems in order to be able to listen on low ports such as 21 (FTP) and 80 (HTTP) but drop root privileges when running; on most POSIX systems only the root user can do this. Versions of Zope prior to 2.6 had less robust versions of this support. Several problems were corrected for the 2.6 release.
The most important thing to remember about this support is that you don't have to start ZServer as root unless you want to listen for requests on "low" ports. In fact, if you don't have this need, you are much better off just starting ZServer as a user account dedicated to running Zope. nobody is not a good idea for this user account, because if any other daemon on a system that ran as nobody was compromised, this would have opened up your Zope object data to compromise.
If you do need to have ZServer listening on low ports, you will need to start zopectl as the root user, and also specify what user ZServer should setuid() to. Do this by setting the effective-user parameter in your Zope instances configuration file, residing in $INSTANCE_HOME/etc/zope.conf and make sure the log and database files are writeable by this user.
Your Zope Installation
To use and manage Zope, you will need a web browser. Zope's management interface is written entirely in HTML, therefore any browser that understands modern HTML allows you to manage a Zope installation. Mozilla, and any 3.0+ version of Microsoft Internet Explorer or Netscape Navigator will do. Other browsers that are known to work with Zope include Opera, Galeon, Konqueror, OmniWeb, Lynx, and W3M.
Start a web browser on the same machine on which you installed Zope and visit the URL
http://localhost:8080/ . If your Zope is properly installed and you're visiting the correct URL, you will be presented with the Zope "QuickStart" screen.
[myimg]upload/quickstart.png[/myimg]
Figure 2-8 Zope QuickStart
If you see this screen, congratulations! You've installed Zope successfully. If you don't, see the Troubleshooting section below.
Logging In
To do anything remotely interesting with Zope, you need to use its "management interface", also known as the ZMI. Zope is completely web-manageable. To log into the Zope management interface, use your web browser to navigate to Zope's management URL. Assuming you have Zope installed on the same machine from which you are running your web browser, the Zope management URL will be http://localhost:8080/manage.
Successful contact with Zope using this URL will result in an authentication dialog. In this dialog enter the "initial" username and password you chose when you installed Zope. You will be presented with the Zope Management Interface (ZMI).
[myimg]upload/zmi.png[/myimg]
Figure 2-9 The Zope Management Interface.
If you do not see an authentication dialog and the Zope Management interface, refer to the Troubleshooting section of this chapter.
Controlling the Zope Process With the Control Panel
When you are using the ZMI, you can use the Zope Control Panel to control the Zope process. Find and click the Control_Panel object in ZMI.
The Control Panel
Figure 2-10 The Control Panel
The Control Panel displays information about your Zope, such as the Zope version you are running, the Python version that Zope is using, the system platform, the INSTANCE_HOME, the ZOPE_HOME, Zope's process id, the Network Services that have been started, how long Zope has been running for, and other installation specifics. Several buttons and links will also be shown.
If you are running Zope on UNIX or as a service on Windows, you will see a button in the Control Panel named Restart. If you click the Restart button, Zope will shut down and then immediately start up again. It may take Zope a few seconds to come back up and start handling requests. You needn't shut your web browser down and restart it to resume using Zope after pressing Restart, just wait for the Control Panel display to reappear.
To shut Zope down from the ZMI, click the Shutdown button. Shutting Zope down will cause the server to stop handling requests and exit. You will have to manually start Zope to resume using it. Shut Zope down only if you are finished using it and you have the ability to access the server on which Zope is running, so that you can manually restart it later.
Controlling the Zope Process From the Command Line
To stop a manually-run Zope on Windows press "Ctrl-C" while the console window under which Zope is running is selected. To stop a Zope on Windows that was run as a service, find the service with the name you assigned to your Zope installed in the Services Control Panel application and stop the service.
To stop Zope on UNIX, do one of the following:
* press "Ctrl-C" in the terminal window from which you started Zope if you started it in the foreground
* if you started Zope in the background, use the zopectl script:
$ ~/myzope/instance/bin/zopectl stop
* use the UNIX "kill" command against the process id in the "var/Z2.pid" file inside of your Zope instance directory:
$ kill `cat var/Z2.pid`
Troubleshooting and Caveats
Running zopectl returns with an OSError
When running Zope on a 2.6.x Linux kernel, Solaris or MaC OSX, zopectl returns with OSError: [Errno 10] No child processes. This is due to a bug in Zope 2.7.0. You have the following options:
* Install a patch currently in CVS. See http://zope.org/Collectors/Zope/1235 for the collector log and a small patch. The patch file is named zdctl.diff. Download it to a temporary directory, eg. /tmp. Then change to the directory $ZOPE_HOME/lib/python/zdaemon (in our previous examples, this would be ~/myzope/zope2.7/lib/python/zdaemon) and run the patch command: patch < /tmp/zdctl.diff. The patch program should respond with an output like patching file zdctl.py.
* Downgrade to a 2.4.x kernel if you are running Linux.
* Work around this issue by placing Zope in the background manually with:
$ nohup ~/myzope/instance/bin/runzope &
Note though that your Zope instance will not be automatically restarted by zdaemon this way; you probably should not use this workaround on a production server.
Browser cannot connect to port 8080
If your browser fails to connect with anything on TCP port 8080, your Zope may be running on a nonstandard TCP port (for example, some versions of Debian Linux ship with Zope's TCP port as 9673). To find out exactly which URL to use, look at the logging information Zope prints as it starts up when started in the foreground, ie. when started with ./runzope or ./zopectl fg. For example:
------
2004-04-21T21:48:27 INFO(0) ZServer HTTP server started at Wed Apr 21 21:48:27 2004
Hostname: arod
Port: 9673
------
2004-04-21T21:48:27 INFO(0) ZServer FTP server started at Wed Apr 21 21:48:27 2004
Hostname: arod
Port: 8021
...
The first log entry indicates that Zope's web server is listening on port 9673 on host arod. This means that the management URL is http://arod:9673/manage.
As mentioned above, Zope only prints to the console if started in the foreground, with ./runzope or runzope.bat, respectively. The same information can be found in the log/event.log file in your INSTANCE_HOME directory.
Certain versions of Microsoft Internet Explorer 5.0.1 and 5.5 have issues with the Zope management interface which manifest themselves as an inability to properly log in. If you have troubles logging in with IE 5.0.1 or IE 5.5, try a different browser or upgrade IE 6.
Forgot administrative password
If you forget or lose the initial user name and password, shut Zope down and change the initial user password with the zpasswd.py script and restart Zope. See the chapter entitled Users and Security for more information about configuring the initial user account.
Customizing your Zope instance
As of Zope 2.7.0, configuration no longer is done with a mix of environment variables and command line options. Instead, there is a directory etc in your instance home, which contains a zope.conf file where numerous configuration directives can be specified. This scheme greatly enhances manageability and configurability for Zope 2.7.x
The
zope.conf file has extensive inline documentation which we will not reproduce here. We will give an overview and some additional hints for the most widely used directives though.
Server stanzas and port-base
The port-base directive together with the stanzas for the individual servers determine the ports those servers listen on. The stanzas are formed with XML-like constructs:
<http-server>
# valid keys are "address" and "force-connection-close"
address 8080
</http-server>
<ftp-server>
...
</ftp-server>
<webdav-source-server>
...
</webdav-source-server>
The address directive determines the port the respective server listens on. The HTTP Server in this example listens on port 8080.
The port-base directive comes in handy if you want to run several Zope instances on one machine. port-base specifys an offset to the port all servers listens on. Let us assume our HTTP Servers address directive is set to 8080 like in our example above, and port-base is specified as 1000. The actual port the HTTP Server will listen on will be 9080. Assuming the FTP Servers address directive is set to 8021, the FTP Server will then listen on port 9021, and so on.
The debug-mode directive
This directive is a switch, specified as either on or off. When set to on (the default), Zope runs in debug mode. This causes Zope to reload Filesystem-based templates in real time and several other settings suitable for development. You should set this directive to off in a productions environment however.
Additional products directories
One of the most useful directive in the authors opinion. You can specify additional Products directories here, ie. places where Zope looks for (possibly third-party) add-on Zope Products. Two directories come to mind: one for commonly used third-party Products like CookieCrumbler or CMF and Plone packages, which I like to keep in /usr/local/zopeproducts (any directory will do, of course). The benefit is better separation of core Zope Products and third-party Add-Ons. The other directory could be of interest for Zope Product developers, which are able to specify a probably version-controlled development directory with this directive.
Switch the User the Zope process runs as: effective-user
This directive causes Zope to setuid(2) to the specified user when run as root on a Unix system. This benefits security a lot, since a compromised Zope cannot as easily damage a whole system. One motivation for running Zope as root in the first place is to be able to bind to privileged ports (ports with numbers below 1024)
Configuring the Session machinery
Use the maximum-number-of-session-objects directive to limit the number of session objects. This value defaults to 1000 objects; 0 means unlimited.
session-timeout-minutes sets the Session timeout in minutes. The default is 20min.
Logging
Three log facilities are provided: access logging, event logging, and trace logging. Access logging logs individual HTTP Requests in a common format, by default to the file log/Z2.log in your instance home. Event logging logs Zope events, for example start/stop information or debugging messages. The Trace logger logs detailed Zope debugging information.
Each log message has an associated severity level, ranging from CRITICAL, ERROR, WARN, INFO to DEBUG and ALL. You can specify a filter for log messages with the level directive inside a logger stanza. Set the level to ALL to get all log messages, or to ERROR or CRITICAL to see only the most serious messages.
The default is to write the messages to a log file; you can however arrange for log messages to be mailed to you or to go to syslog(3) (on Unix) or the NT event log (on MS Windows)
For further documentation, see the inline comments in zope.conf
When All Else Fails
If there's a problem with your installation that you just cannot seem to solve, do not despair. You have many places to turn for help, including the Zope maillists and the #zope IRC channel.
If you are new to open source software, please realize that, for the most part, participants in the various "free" Zope support forums are volunteers. Though they are typically friendly and helpful, they are not obligated to answer your questions. Therefore, it's in your own self-interest to exercise your best manners in these forums in order to get your problem resolved quickly.
The most reliable way to get installation help is to send a message to the general Zope maillist detailing your installation problem. For more information on the available Zope mailing lists, see the Resources section of Zope.org. Typically someone on the "[email protected]" list will be willing to help you solve the problem.
For even more immediate help, you may choose to visit the #zope channel on the OpenProjects IRC (Internet Relay Chat) network. See the OpenProjects website for more information on how to connect to the OpenProjects IRC network.
If you are truly desperate and under a time constraint that prohibits you from utilizing "free" support channels, Zope Corporation provides for-fee service contracts which you can use for Zope installation help. See Zope.com for more information about Zope Corporation service contracts.