Building and installing Zope from source
----------------------------------------
Welcome to Zope! This document describes building and installing
Zope on UNIX and Linux.
See WINDOWS.txt for information about Windows. See the PLATFORMS
directory for notes about various other platforms.
System requirements when building from source
* bash or another Bourne shell variant
* Python 2.4.2 or later installed somewhere in the system PATH
(Python 2.5 is not supported)
* GNU make
* A C compiler (gcc recommended)
Recommendations
- You are recommended to build and install Zope as a non-root user.
Building Zope
To build Zope, run the conventional UNIX build sequence from within
the Zope source tree::
./configure --prefix=/where/to/install/zope
make
If you do not specify a '--prefix' option, during a later step, Zope
will be installed into a default location.
If the configure script cannot find a suitable Python interpreter
for use with Zope, it will complain with an informative error
message. If this happens, you may use the '--with-python'
command-line option to 'configure' to specify which Python
interpreter to use. Run './configure --help' to see other
command-line options available via the configure script.
Optional: Building and Installing Zope 'In-Place' (SVN checkouts only)
Older versions of Zope were typically run directly from the
'source' directory itself. This is useful for development
purposes. You can regain that behavior by performing the
following sequence of commands within a Zope source directory:
./configure
make instance
This command also creates an administrative user with the
specified username and password.
WARNING: "make instance" doesn't work on FreeBSD 5.0 and
presumably other platforms. You should either use GNU make
(gmake instance), or use "make install" instead.
Making an "In-Place" instance builds the binary files and creates
the files necessary for a Zope instance to be run directly
within the build directory (e.g. 'in-place'). You may start
Zope by running::
./bin/zopectl start
See ./log/event.log for any output which may happen during
start of Zope. If anything goes wrong you will see there.
If you use
./bin/zopectl fg
instead, the output is generated to the screen. In this case
Zope does not detach from terminal.
Optional: Building Zope Using The "Clean-Source-Tree" Method
You can run the 'configure' command from outside of the Zope
source tree. If you do so, the makefile will be written to your
current directory. The files generated by the build process (via
'make') will be written to the directory from which you run
'configure'. You can then use 'make install' to install these
files to their canonical locations. This feature is to support
source locations which are not writable.
Installing Zope
To install Zope to the place you've specified via the '--prefix'
option (or to the default location if you didn't specify a prefix),
type::
make install
Creating a Zope Instance Home
Once you've performed the install step, to begin actually using
Zope, you will need to create an "instance home", which is a
directory that contains configuration and data for a Zope server
process. The instance home is created using the 'mkzopeinstance.py'
script::
/where/to/install/zope/bin/mkzopeinstance.py
You will be asked to provide a user name and password for an
administrator's account during 'mkzopeinstance'. Command-line
options to 'mkzopeinstance' are available, and can be investigated
by running 'mkzopeinstance.py --help'.
Starting Zope
Once an instance home has been created, the Zope server can now be
started using this command:
/location/of/zope/instance/bin/zopectl start
During start, zope emits log messages into ./log/event.log
You can examine it with the usual tools (cat, more, tail)
and see if there are any errors preventing zope from starting.
/location/of/zope/instance/bin/zopectl fg
can be used to instead output these messages to the console. This
way zope does not detach from terminal.
If you get errors indicating that addresses are in use, then you
will have to supply arguments to runzope to change the ports used
for HTTP or FTP. The default HTTP and FTP ports used by Zope are
8080 and 8021 respectively. You can change the ports used by
editing ./etc/zope.conf apropriately.
The section usually is like this:
# valid keys are "address" and "force-connection-close"
address 8080
# force-connection-close on
address can just be a port number as shown, but also a host:port
pair to bind to a specific interface only.
zopectl can be linked as rc-script in the usual start directories
on linux or other system V unix variants.
You can use zopectl interactively as a command shell by just
calling it w/o any arguments. Try help there and help
to find out about additionally commands of zopectl. These commands
work also on command line.
By default, 'zopectl start' will start a background process that
manages Zope and 'zopectl stop' will stop the background process.
Logging In To Zope
Once you've started Zope, you can then connect to the Zope webserver
by directing your browser to::
http://yourhost:8080/manage
.. where 'yourhost' is the DNS name or IP address of the machine
running Zope. If you changed the HTTP port as described, use a port
number of 8080 + the port-base value.
You will be prompted for a user name and password. Use the user name
and password you provided in response to the prompts issued during
the "make instance" process.
Now you're off and running! You should be looking at the Zope
management screen which is divided into two frames. On the left you
can navigate between Zope objects and on the right you can edit them
by selecting different management functions with the tabs at the top
of the frame.
If you haven't used Zope before, you should head to the Zope web
site and read some documentation. The Zope Book is a good place to
start. You can access the Zope Book at:
http://www.zope.org/Documentation/Books/ZopeBook
Integrating Zope With An Existing Webserver
Zope doesn't require any existing webserver to run, but you can
integrate it with other webservers as necessary. See the
WEBSERVER.txt file for more information about configuring Zope with
an existing web server. There is also information about integrating
Zope with existing webservers on the Zope.org website.
Troubleshooting
- This version of Zope requires Python 2.4.1 or better.
- The Python you run Zope with *must* have threads compiled in,
which is the case for a vanilla build. Warning: Zope will not run
with a Python version that uses libpth. You *must* use
libpthread.
- To build Python extensions you need to have Python configuration
information available. If your Python comes from an RPM you may
need the python-devel (or python-dev) package installed too. If
you built Python from source all the configuration information
should already be available.
- See CHANGES.txt for important notes on this version of Zope.