Skip to content
This repository

HTTPS clone URL

Subversion checkout URL

You can clone with HTTPS or Subversion.

Download ZIP

Linux/BSD/OSX Installer

README.rst

Plone 4.3.3: Unified Installer

The Plone Unified Installer is a source-installation kit that installs Plone and its dependencies from source on most Unix-like platforms. The kit includes Plone and Zope and will download components like Python if needed. Python is installed in a way that will not change or interfere with your system Python.

This version includes Plone 4.3.3, Zope 2.13.x, and uses Python 2.7.x.

Feedback/bugs to Plone Development Workspace for component: Installer (Unified)

For a guide to installing and maintaining Plone, see Installing and maintaining Plone sites

If you are a deploying Plone for production, read Basics of Plone Production Deployment before continuing.

Important: Back up your existing Plone site prior to running the installer or running buildout to update.

Outline of this document

Installation Instructions

The installer will compile Python, Zope, and key required libraries from source on an as-needed basis. (Basic build tools and common libraries are required. See Utility Dependencies and Libraries Required below.

PLEASE NOTE: You have the option to run the installation as root or a normal user. There are serious security implications to this choice.

The non-root method produces an install that will run the Zope server with the same privileges as the installing user. This is probably not an acceptable security profile for a production server, but is much easier for testing and development purposes or if you take care to set users and privileges yourself.

The 'root' method produces an install that runs the Zope server as a distinct user identity with minimal privileges (unless you add them). Providing adequate security for a production server requires many more steps, but this is a better starting point.

PLEASE NOTE: You have the option to install Plone as a standalone (single-instance) setup or as a clustered (ZEO) setup.

The clustered (ZEO) setup will take advantage of multi-core CPUs and is recommended for a production deployment, while the standalone method is easier for development or testing.

For more detail on both root/non-root and ZEO/standalone choices, see Installing on Linux / Unix / BSD in the Plone.org documentation section.

For a non-super-user (rootless) installation

If you run the installation while logged in as a normal (non-root) user, Python/Zope/Plone will be built at $HOME/Plone (the user's home directory, Plone subdirectory). You will need to start Zope using the user identity used for the build, and it will run with the privileges of that user.

To install Plone 4.3.3 in a stand-alone (single Zope instance) configuration:

  • cd to the installer directory and issue the following command:

    >> ./install.sh standalone
    

To install Plone 4.3.3 in a ZEO Cluster (ZEO server, 2 clients) configuration:

  • cd to the installer directory and issue the following command:

    >> ./install.sh zeo
    

For a super-user (root) installation

If you run the installation with root privileges, it will install Python/Zope/Plone to /usr/local/Plone.

[Darwin (OS X) Note: Under Darwin, the default installation is to /Applications/Plone for the root install. Please replace /usr/local with /Applications in the instructions below.]

Two Plone users will be created: plone_daemon and plone_buildout. You will need to start Plone as plone_daemon and run buildout as plone_buildout. The install will also create a plone_group group that includes both plone users.

To install Plone 4.3.3 in a stand-alone (single Zope instance) configuration:

  • cd to the installer directory and issue the following command:

    >> sudo ./install.sh standalone
    

    or on a sudo-less system:

    >> su; ./install.sh standalone
    

To install Plone 4.3.3 in a ZEO Cluster (ZEO server, 2 clients) configuration:

  • cd to the installer directory and issue the following command:

    >> sudo ./install.sh zeo
    

    or on a sudo-less system:

    >> su; ./install.sh zeo
    

The "sudo" utility is required for a root install. This security utility is included with most recent Unix workalikes and is easily installed on other systems. On BSD-heritage systems, this in the security directory of the ports collection.

Installation Options

Usage: [sudo] install.sh [options] standalone|zeo

Install methods available:

standalone: install standalone zope instance
zeo: install zeo cluster

Use sudo (or run as root) for root install.

Options

--target=pathname
 

Use to specify top-level path for installs. Plone instances and Python will be built inside this directory. Default is /usr/local/Plone for root install, $HOME/Plone for non-root.

PLEASE NOTE: Your pathname should not include spaces.

--instance=instance-name
  Use to specify the name of the operating instance to be created. This will be created inside the target directory. Default is 'zinstance' for standalone, 'zeocluster' for ZEO.
--clients=client-count
  Use with the "zeo" install method to specify the number of Zope clients you wish to create. Default is 2.
--daemon-user=user-name
  In a root install, sets the effective system user for running the instance. Default is 'plone_daemon'. Ignored for non-root installs.
--owner=owner-name
  In a server-mode install, sets the overall system owner of the installation. Default is 'plone_buildout'. This is the user id that should be employed to run buildout or make src or product changes. Ignored for non-root installs.
--group=group-name
  In a server-mode install, sets the effective system group for the daemon and buildout users. Default is 'plone_group'. Ignored for non-server-mode installs.
--with-python=</full/path/to/python2.7>
  If you have an already built Python that's adequate to run Zope / Plone, you may specify it here. virtualenv will be used to isolate the copy used for the install. The specified Python will need to have been built with support for libz and libjpeg and include the Python Imaging Library.
--build-python If you do not have a suitable Python available, the installer will build one for you if you set this option. Requires Internet access to download Python source.
--password=InstancePassword
  If not specified, a random password will be generated.
--libjpeg=<auto|yes|no>
  Overrides the automatic determination of whether and where to install the libjpeg JPEG library.
--readline=<auto|yes|no>
  Optional. Installs a local readline library. Only necessary on platforms with odd libraries (like OS X Leopard).
--without-ssl Optional. Allows the build to proceed without ssl dependency tests.
--static-lxml Forces a static build of lxml's libxml2 and libxslt dependencies. Requires Internet access to download components.

Note that you may run install.sh repeatedly for the same target so long as you either use a different installation method or specify different instance names. Installations to the same target will share the same Python and egg/download cache.

Upgrade From Plone 2.5 or Non-Buildout 3.x

See UPGRADING.txt

Utility Dependencies

Most of these are included with system "build" kits.

  • gcc
  • g++ (gcc-c++)
  • GNU make
  • GNU tar
  • patch
  • gunzip and bunzip2
  • posix-compliant /bin/sh
  • curl or wget

Libraries Required

Install libraries prior to running installer. Development versions of some packages are required for headers. Debian/Ubuntu package names are included below. RPM equivalents follow in a separate subsection.

Required if you use your system Python 2.7.x

  • build-essential
  • libjpeg-dev
  • python-dev
  • libxml2-dev
  • libxslt1-dev

Required if you need to build Python 2.7.x

  • build-essential
  • libssl-dev
  • libz-dev
  • libjpeg-dev
  • readline-dev
  • libxml2-dev
  • libxslt1-dev

LibXML2/LibXSLT versions

Many older systems have inadequate libxslt/libxml libraries. There is no point in installing old libraries. Plone requires libxml2 >= 2.7.8 and libxslt 1.1.26. In this case, use the --static-lxml option to get the installer to build and statically link these libraries.

RPM Equivalents

These are the RPM equivalents for the Debian/Ubuntu packages listed above:

  • gcc-c++
  • patch
  • openssl-devel
  • libjpeg-devel
  • libxslt-devel
  • readline-devel
  • make
  • which

Optional

Mainly used to support indexing of office-automation documents.

  • wv (used to index Word documents)

    wv may be installed after Plone install.

  • poppler-utils (used to index PDFs)

    poppler-utils may be installed after Plone install.

Install Location, Root Install

  • Base install at /usr/local/Plone by default. This may be changed with the --target installation option. If you change it, you'll also need to change the paths below.
  • Python installed at /usr/local/Plone/Python-2.7
  • For ZEO Cluster:
    • ZEO cluster (server and 2 clients) installed and configured at /usr/local/Plone/zeocluster Both --target and --name options may change this.
    • Add-on Products folder at /usr/local/Plone/zeocluster/ products. (You may also install products via buildout.)
    • Data.fs (ZODB) at /usr/local/Plone/zeocluster/var/filestorage
    • adminPassword.txt at /usr/local/Plone/zeocluster/adminPassword.txt
  • For Stand-Alone:
    • Zope Instance installed and configured at /usr/local/Plone/zinstance Both --target and --name options may change this.
    • Add-on Products folder at /usr/local/Plone/zinstance/products (You may also install products via buildout.)
    • Data.fs (ZODB) at /usr/local/Plone/zinstance/var/filestorage
    • adminPassword.txt at /usr/local/Plone/zinstance/adminPassword.txt

Install Location, Root-less Install

  • Base install at $HOME/Plone, where $HOME is the user's home directory, by default. This may be changed with the --target installation option. If you change it, you'll also need to change the paths below.
  • Python installed at $HOME/Plone/Python-2.7
  • For ZEO Cluster:
    • ZEO cluster (server and 2 clients) installed and configured at $HOME/Plone/zeocluster Both --target and --name options may change this.
    • Add-on Products folder at $HOME/Plone/zeocluster/products (You may also install products via buildout.)
    • Data.fs (ZODB) at $HOME/Plone/zeocluster/var/filestorage
    • adminPassword.txt at $HOME/Plone/zeocluster/adminPassword.txt
  • For Stand-Alone:
    • Zope Instance installed and configured at $HOME/Plone/zinstance Both --target and --name options may change this.
    • Add-on Products folder at $HOME/Plone/zinstance/products (You may also install products via buildout.)
    • Data.fs (ZODB) at $HOME/Plone/zinstance/var/filestorage
    • adminPassword.txt at $HOME/zinstance/adminPassword.txt

Startup/Shutdown/Restart/Status instructions

Root Install

To start Plone:

>> sudo -u plone_daemon /usr/local/Plone/zeocluster/bin/plonectl start

To stop Plone:

>> sudo -u plone_daemon /usr/local/Plone/zeocluster/bin/plonectl stop

To restart Plone:

>> sudo -u plone_daemon /usr/local/Plone/zeocluster/bin/plonectl restart

To check status:

>> sudo -u plone_daemon /usr/local/Plone/zeocluster/bin/plonectl status

Replace "zeocluster" with "zinstance" or your instance name if this wasn't a standard zeo install.

Root-less Install

To start Plone:

>> $HOME/Plone/zeocluster/bin/plonectl start

To stop Plone:

>> $HOME/Plone/zeocluster/bin/plonectl stop

To restart Plone:

>> $HOME/Plone/zeocluster/bin/plonectl restart

To check status:

>> $HOME/Plone/zeocluster/bin/plonectl status

Replace "zeocluster" with "zinstance" or your instance name if this wasn't a standard zeo install.

Ports

  • Stand-Alone:

    • Zope server runs on port 8080

      Edit buildout.cfg and run bin/buildout to change port.

  • ZEO Cluster:

    • ZEO server runs on port 8100
    • ZEO client1 runs on port 8080
    • ZEO client2 runs on port 8081
    • ...

Edit buildout.cfg and run bin/buildout to change ports.

Post-installation instructions

You should be able to view the welcome page at http://localhost:8080/

That page offers options to create a new Plone site and to use the Zope Management Interface (ZMI) for lower-level control. Among the ZMI options is the ability to create additional Plone instances inside the Zope Zope object database.

(Use the admin password provided at yourinstance/adminPassword.txt)

Select "Plone site" from the "Add item" drop-down menu near top right to add a Plone site. This only needs to be done once for each Plone site you wish to add.

To change the admin password, click the "Password" link for the admin user at http://localhost:8080/acl_users/users/manage_users

Password changes will not be reflected in adminPassword.txt

Root Install Notes

If you install as root, the installer will set you instance up for operation under specific user and group ids.

user:

plone_daemon

This user id will be used to own the "var" and "backup" components of the install. You should run Plone using this user id:

sudo -u plone_daemon bin/plonectl start
user:

plone_buildout

This user id will own everything else in your installation. You must run buildout using this user id:

sudo -u plone_buildout bin/buildout
group:

plone_group

The id, "plone" unless you specify otherwise, will be created if it doesn't exist.

The Zope daemon will be set up run under this user id, and the user will be the owner of the files in the instance and buildout cache subdirectories.

This means that you will need to prefix your start/stop/buildout commands with:

sudo -u plone

to make sure they run under the correct user id.

If you try to start Zope as root, it will automatically switch effective ID to the configured user. However, you'll need to be sure to run buildout (for configuration updates) via sudo. Running buildout as root is a security risk.

Installation Errors

The installer may fail for a variety of reasons. If the error message is not helpful, check the detailed installation log, install.log, to look for problems. You may be able to get help on the #plone IRC channel on freenode.net, or from the plone-users or plone-setup mailing lists. See Plone Support Center. If you suspect the error is due to a bug in the installer, see the Installer Bug Reports section below.

Errors building dependencies

If the install fails while trying to build a library like libjpeg or readline, the best thing to do is nearly always to install an up-to-date system library to meet the dependency. Then clean up the aborted install and try again.

Built Python does not meet requirements

This error is usually caused by a failure of the Python build to find system libraries. This should only happen, though, if the Unified Installer itself did find the libraries. Otherwise, the installation would have failed much earlier.

On Debian, Ubuntu systems, the likely cause is that your system is not accurately reporting its "multiarch" architecture. This seems to mainly happen on systems that have been upgraded from development versions.

Other systems may just be using unexpected locations for libraries. This is common on systems that have uncomfortable relationships with the GNU toolset and install GNU tools in separate locations.

Whatever the cause, the general solution is to tell the Python setup routines about the unexpected library location using the LDPATH environment variable. For example, if your readline library was in /usr/lib/oddspot, you could try running the installer with a command like:

LDPATH="-L/usr/lib/oddspot" ./install.sh zeo ...

Updating After Installation

Always back up your installation before customizing or updating.

Customizing the installation

You may control most aspects of your installation, including changing ports and adding new packages and products by editing the buildout.cfg file in your instance home.

See tutorial Managing projects with Buildout for information on buildout options.

Apply settings by running bin/buildout in your buildout installation directory.

Third-party products installed

  • PIL (Python Imaging Library)
  • libjpeg (JPEG library)
  • libreadline (terminal mode command-line and prompt editing)
  • Cheetah, Paste, PasteDeploy, PasteScript, ZopeSkel
  • lxml, libxml2, libxslt

Platform Notes

The install script requires a POSIX-compliant version of sh. If your version of sh fails on test expressions, you may need to edit the install script to specify use of zsh, bash or a later version of sh.

The install script requires several GNU build utilities such as gcc, g++, make, gunzip, bunzip2 and tar.

The install script tries to find readline and libjpeg libraries. If it can't find them, it installs them locally in the target directory. If the library detection code in the installation script doesn't meet your needs, you may force a particular choice by editing the script.

Note that readline installation is forced on OS X, where the default readline library is incomplete.

Mac OS X

OS X users will generally need to install XCode and XCode Command Line Tools. Some have had luck using Homebrew to provide GNU build tools. We only test with XCode.

XCode command-line tools have a separate step in recent versions of XCode. If you seem to be missing gcc, you've missed that install step.

Building Python libraries with C-language components requires an extra step in XCode 5.1+. See Apple's release notes for 5.1. https://developer.apple.com/library/mac/releasenotes/DeveloperTools/RN-Xcode/xc5_release_notes/xc5_release_notes.html#//apple_ref/doc/uid/TP40001051-CH2-SW1 The Unified Installer takes care of this for you when building the initial Plone, but you need to supply the environment flags when adding new Python eggs that have C-language components.

MacPorts

If you're using MacPorts, it's probably best to follow an all-or-nothing strategy: either use ports to pre-install all the dependencies (Python-2.7, libxml2, libxslt, readline and libjpg), or don't use it at all.

Mac OS X Server

If you are using LDAP for directory services, the install.sh script may be unable to reliably create users and groups.

In a custom environment such as this, scripted creation of users and groups for a root installation of Plone may be inappropriate.

You can use Workgroup Manager (Apple Server Admin Tools) to create groups that are typical to a production installation of Plone:

  • plone
  • zeo

then create users with UIDs below 500:

  • plone
  • zeo

For each user: - match the Primary Group ID to the corresponding group - decide whether to allow a shell - specify the path to the home directory.

For root installation of a ZEO cluster on Mac OS X, custom paths might be:

  • /Applications/Plone/homes/plone
  • /Applications/Plone/homes/zeo

when scripted installation of Plone proceeds, it will make that directory hierarchy for you.

After you configure users and groups to suit your planned use of Plone, you can re-run install.sh.

OpenBSD/NetBSD

The Unified Installer is not smart enough to install Python 2.7.x on OpenBSD/NetBSD; it just requires too many platform- specific patches. Instead of having the installer build Python, just make sure Python 2.7 is preinstalled with system packages or ports.

Test builds on OpenBSD 4.2 succeeded with the following packages pre-installed:

bzip2-1.0.4
block-sorting file compressor, unencumbered
python-2.7.3
interpreted object-oriented programming language
python-expat-2.6.7
expat module for Python

If you are unable to install python-expat-2.6.7, you may need to install the xbase file set, which includes expat in some versions of OpenBSD (4.2).

Unix/Solaris/etc.

If you're using an *nix system that does not use GNU build tools, you probably already know that installing open-source software based on GNU tools requires some extra work. Ideally, you'll have already installed the full GNU build tool kit and become proficient with specifying compile and link paths to them via CFLAGS and LDFLAGS. Expect to use those skills when installing Plone. If CFLAGS/LDFLAGS/CPPFLAGS are in the environment when the installer is run, it will use them rather than set its own. As with other environments, preinstall as many dependencies as possible.

Installing behind HTTP proxies

The installer should not need to access network resources for most installs, as it includes the needed components. However, if you need to use the static xml build, network access will be required. Network access will also be required when you run buildout later.

If you're behind an HTTP proxy, you're going to need to take special measures to access the larger network.

As with Python setuptools in general, indicate an HTTP proxy by setting the http_proxy environment variable:

export http_proxy=http://192.168.1.25:80

before running the installer or buildout.

If you are using sudo, an extra step is needed to make sure the environment variable passes to the invoked command. Use:

sudo -E ./install.sh ...

or:

sudo -E -u plone_buildout bin/buildout

to pass the execution environment via sudo.

Uninstall instructions

  1. Stop Plone
  2. Remove folder /usr/local/Plone or $HOME/Plone

Backup instructions

  1. Stop Plone

  2. Back up folder /usr/local/Plone or $HOME/Plone:

    >> tar -zcvf Plone-backup.tgz /usr/local/Plone
    

Live backup is possible. See Backup Plone

Coexistence with System Python

The Python installed by the Unified Installer should not interfere with any other Python on your system. The Installer bundles Python 2.7.6, placing it at /usr/local/Plone/Python-2.7 or $HOME/Plone/Python-2.7

Developer Options

After installation, read the instructions at the top of the develop.cfg file at the top of the instance directory. This provides support for building a development environment.

Custom buildout.cfg Template

You may specify --template= to pick a file to use as a template for the buildout.cfg file. The file must be located in buildout_templates, and should be generally modified on the buildout.cfg included with the installer. The safest customizations will be to add eggs, parts or version pinnings.

The purpose of this option is to allow for feature packaging for particular use cases with common add-on needs.

Installer Bug reports

Please use the Plone issue tracker at https://dev.plone.org for all bug reports. Specify the "Installer (Unified)" component.

Credits

The Unified Installer was originally developed for Plone 2.5 by Kamal Gill. Adaptation to Plone 3.x, 4.x and buildout: Steve McMahon (steve@dcn.org) Maintainer for Plone 3.x, 4.x: Steve McMahon

Thanks to Martin Aspeli and Wichert Akkerman for vital hints and suggestions with the buildout version.

Thanks for Naotaka Jay Hotta for suggesting -- and offering an initial implementation for -- stand-alone and cluster configuration options.

Thanks to Larry T of the Davis Plone Group for the first implementation of the rootless install.

Thanks to Barry Page and Larry Pitcher for their work on the init scripts.

Something went wrong with that request. Please try again.