Setting up A New.Zope.Org Appserver From Scratch

Instructions for installing a new.zope.org appserver from scratch:

Set up a machine with the latest RedHat Linux release (at least RedHat 7.1). Ensure that the at least the following subsystems are installed:

      gcc
      emacs
      vim
      X11
      openldap
      sudo
      man2html

    (see the end of this document for notes on building
     on non-Redhat systems)

As the root user, create a "zope" user on the newly set up system:
```
      # /usr/sbin/useradd zope
```
Change the zope user's password:
```
      # passwd zope
```
Add the Zope user to the /etc/sudoers file by adding the following line to that file:
```
      zope    ALL=(ALL) ALL
```
Log in as the zope user and "cd" to the zope user's home directory:
```
      # su - zope; cd ~
```
Set the CVS checkout mechanism to SSH by adding this line to the Zope user's .bash_profile file:
```
      export CVS_RSH=ssh
```
Log out as the Zope user and log back in (for the CVS_RSH envvar to take effect).
Ensure that the machine has Internet access.

Perform an anonymous checkout of the "site layout" facility:

      $ cvs -d :pserver:[email protected]:/cvs-zopeorg login
        Logging in to...
        CVS password: {"anonymous"}
      $ cvs -z7 -d :pserver:[email protected]:/cvs-zopeorg co -d \
        site-layout NZO_SiteLayout

Use the site-layout facility to create a base install of Python, Zope, ZEO, CMF software:

      $ site-layout/buildout zope

        {churn, churn, churn}

    When the process is finished, you will have the following
    directories in the "zope" user's home directory::

      src -- "pristine" sources for Python, Zope, ZEO, and CMF
      opt -- binary (or psudobinary) builds for Python, Zope, ZEO, and CMF
      doc -- various documentation texts
      bin -- directory containing symlinks to Python binaries

Use the site-layout facility to install the python-ldap Python module:

      $ site-layout/buildout ldap-client

        {churn, churn, churn}

    When the process is finished, some software will be added to both
    'src' and 'opt', and the local Python will have the python-ldap
    module installed via distutils.

Use the site-layout facility to install an INSTANCE_HOME directory and requisite Zope products. When prompted by sudo for a password, enter the zope user's password:

      $ site-layout/buildinstance

        {churn, churn, churn}.. {ask for password}.. {churn, churn}

    This buildout uses Tres Seaver's "zopectl" utility as a front-end
    for Zope startup, shutdown, and configuration.  The default
    buildinstance will install a Zope INSTANCE_HOME in the
    var/Instance directory that will run on the HTTP port 8080 and
    that does not attempt to use a ZEO storage server.  A "zopectl"
    configuration file will be written to the etc/zope-Instance.conf
    file, a startup script will be installed in the bin/zctl-Instance
    file and an rc script which calls this startup file will be
    written to the /etc/rc.d/init.d/zope_Instance file (set to start
    at runlevels 2345).  The config files and startup scripts should
    be somewhat self-documenting.

    To install an additional INSTANCE_HOME with a different name and
    different port/password settings or to change the default instance
    settings, use a special set of environment variables *before* the
    "site-layout/buildinstance" command.  For instance::

      $ INSTANCE_NAME=Instance2 \
        USE_ZEO_SERVER=1 \
        ZEO_SERVER_HOST=storage \
        ZEO_SERVER_STORAGE=Main \
        INSTANCE_HTTP_PORT=8081 \
        INSTANCE_FTP_PORT=8022 \
        INSTANCE_DAV_PORT=9801 \
        INSTANCE_PASSWD=456 \
        site-layout/buildinstance

    The following environment variables are supported::

     INSTANCE_NAME={var directory name, default "Instance"}
     INSTANCE_HTTP_PORT={HTTP TCP port, default "8080"}
     INSTANCE_FTP_PORT={FTP TCP port, default "8021"}
     INSTANCE_DAV_PORT={DAV TCP port, default "9800"}
     INSTANCE_MONITOR_PORT={monitor TCP port, default "None"}
     INSTANCE_PASSWD={password for access and inituser files, default "123"}
     USE_ZEO_SERVER={1 or 0 depending on whether you want to use a ZEO server}
     ZEO_SERVER_HOST={ZEO server hostname, default 'localhost'}
     ZEO_SERVER_PORT={ZEO server portname, default '8001'}
     ZEO_SERVER_STORAGE={storage name on ZEO server, default 'Main'}

Start the new Zope instance (assuming you've got your storage server set up correctly or you're not using a storage server):

       sudo /etc/rc.d/init.d/zope_{INSTANCE_NAME} start

    You may also start the instance by invoking the zopectl script for
    the instance::

       bin/zctl-{INSTANCE_NAME} start

    You can get an interactive session with zopectl by entering::

       bin/zctl-{INSTANCE_NAME}

    All Zope logfiles are written to the "log" directory inside a
    subdir named after your Zope's INSTANCE_NAME.  To ensure the site
    started correctly, examine the "debug.log" logfile for your
    instance.

If the instance starts, you're ready to visit Zope and set up an NZO portal.

Setting up an NZO portal

Visit the Zope Management Interface on your nzo appserver instance in a browser. (The default port is 8080. Log in using the username "admin", and the password "123" or the password you chose via INSTANCE_PASSWORD).
Create a CMF Site instance in the root folder named "ZopeOrg" its metadata settings (such as title and whatnot) are not meaningful, as they will be replaced automatically.

Inside the newly created CMF Site, create and save an External Method named "setupZopeOrg" with the following parameters:

     Id:  setupZopeOrg
     Title:  (None)
     Module Name: ZopeOrg.setupZopeOrg
     Function Name: setupZopeOrg

 - Click the "Test" tab of the setupZopeOrg external method.  A
   Zope.org "skeleton" site will be created.

 At this point, you should be able to navigate the ZopeOrg CMF Site
 and browse "skeleton" content.

Making Changes to Disk-Based Software

Your instance home contains links to Zope Products required for NZO. During the buildout process, these Products were created in the "src" directory via anonymous CVS checkout. They were then copied over to the "opt" directory for use in the instance.

The ZopeOrg disk-based Product (var/Instance/Products/ZopeOrg) is where most of the interesting software is, including skins. During the buildout process, this Product (as well as all other products) are checked out from cvs.zope.org in "anonymous, pserver" mode, so by default you cannot commit changes to the product back to the NZO repository by doing a "CVS commit" within any given Product directory in your instance home.

We suggest that if you want to contribute changes to the ZopeOrg Product, that you make a writable checkout of the ZopeOrg product and make changes within it:

    cd tmp
    export CVS_RSH=ssh
    cvs -d :ext:[email protected]:/cvs-zopeorg co -d ZopeOrg \
     Products/ZopeOrg-NV

This will require that read/write CVS access be given to "yourname" in the CVS repository. Paul Everitt ([email protected]) can provide this access upon request.

You can link this writable checkout into your instance home by doing something like:

    rm ~/var/Instance/Products/ZopeOrg
    ln -s ~/tmp/ZopeOrg ~/var/Instance/Products

The same general pattern applies for every Product used in your instance home.

Notes for installing on non-RedHat systems

You don't need the init scripts. Pass in NON_REDHAT=1 as an argument to buildinstance, e.g.:

    NON_REDHAT=1 site-layout/buildinstance

This makes the sudo parts of the script that try to install things into /etc/rc.d/init.d and /etc/logrotate.d go away.

Notes for installing on Debian

You'll need to get the following debian packages to service the instance dependencies:

     libldap2-dev