Installing on Linux / Unix / BSD
The basics of installing Plone on Windows, OS X, Linux, *BSD and nearly every other platform.
1. What is the Unified Installer?
A brief introduction to the installer, the case for using it, its options and recent changes.
The Unified Installer is a source installation kit for installing Python, Zope, Plone and their dependencies on Unix-like platforms. It has two major components:
- The source packages for Python, Zope, Plone, a couple of system libraries and some Python libraries;
- An installation script that uses the packages to create a ready-to-run, relatively self-contained, Python/Zope/Plone install that meets the Plone community's best-practices standards.
The new Zope/Plone install will use its own copy of Python, and the Python installed by the Unified Installer will not replace your system's copy of Python. You may optionally use your system (or some other) Python, and the Unified Installer will use it without modifying it or your site libraries.
Why the Unified Installer? Why Not System Packages/Ports?
On the Plone help lists and channel, the suggestion to "just use the Unified Installer" often draws one of two reactions:
I prefer to manage the source install myself, picking all the target directories;
There's nothing wrong with that, though if you use the Unified Installer's target directories you may find it easier to get help from the Plone community.
If you still choose to install by hand, that's fine. You may still find it convenient to download the Unified Installer in order to get all the packages together, and you may find it useful to read the UI's install.sh script for ideas on building particular components.
I prefer to use my platform's ports/packages mechanism.
The history of platform packages for Zope and Plone is a troubled one. Platform packages have been of uneven quality and have used installation trees that make it difficult for the community to offer help when problems occur. Also, platform packages have historically been vulnerable to changes in the system Python. Zope/Plone is very picky about the version of Python used to run it, and an update of the system Python when some other item is installed can easily break Zope/Plone. At this point, you may be thinking that this just means that the packages have poorly specified dependencies. The Unified Installer was created because generation after generation of packages did not solve this problem.
Major Unified Installer Options
The Unified Installer for Plone has three major options:
- Install as root or normal user;
- Install as a ZEO Cluster, or a stand-alone Zope;
- Install the full kit, or just a single running instance.
Each of these options are described in a separate section.
Note: Prior versions of the Unified Installer do not have these options
Changes for Plone 4
- The installer now includes a develop.cfg configuration file, which you may use after the initial installation to configure a common development environment. To use it, run buildout with the command:
bin/buildout -c develop.cfg
- The installer now requires that SSL development libraries be preinstalled on your system (usually done with openSSL). If it can't find them, it halts. If you wish, you may bypass this requirement, which will result in an installation that can't use ESMTP for mail.
Changes for Plone 3.1
- The Unified Installer now uses buildout to configure Plone instances, which makes it much easier for you to control add-ons and upgrade your Plone installation.
- It's much easier to add additional Zope/Plone instances to an existing install base.
- There are additional options for:
- Controlling the installation target directory;
- Setting a user other than "admin" and/or setting a password of your choice;
- Using an already installed Python 2.4 (possibly the system copy). virtualenv is used to isolate the new installation so that your system Python is not touched.
- If libjpeg or libz installation is required, it's done locally to the new install. Even in a root-mode install, your system libraries are not touched.
Changes for Plone 3
If you've used the Unified Installer for prior versions of Plone, you'll already know that the options above are new. There are a few additional changes:
- The installation script tries to determine whether or not you need new builds of the libz and libjpeg. If you don't, it won't build them.
- The UI now works more easily with odd-duck platforms like Solaris, where common GNU build tools may be in uncommon locations.
- This version omits some optional products (TextIndexNG#, ReportLab) bundled with prior versions.
- This version includes the new Python easy install kit, though it doesn't use it.
2. Root or User Install?
The cases for and against installation as the root user.
The install.sh script for the Unified Installer may be run as root (typically via sudo) or as a normal user. Key differences are:
The root (production) install:
- Installs by default to /usr/local/Plone;
- Creates a "plone" user, sets this user as owner of the data files, and configures Zope to run as the effective user "plone".
- Program and configuration files are owned by the root user, and should not be writable by the Zope process.
The normal (non-root) user install:
- Installs by default to $HOME/Plone;
- Is meant to be run by and under the effective user id of the installing user.
Why Choose root or normal?
Installing as root (or with root privileges via sudo) may be the best choice for a production installation of Plone. Since this install runs under the user id of a user created specifically for this purpose, it should have a more controllable level of access to resources. It is a generally accepted "best practice" to run persistent processes (like Zope) as unique users with limited rights.
If you install via root, though, be careful not to run "sudo bin/buildout" except in offline mode since this would immediately run setup downloaded programs. Instead, obtain distribution files from validated sources, put them in buildout-cache/download/dist and run buildout in offline mode.
Installing as a normal user (perhaps with your own user identity) may be a better choice for a test or development instance. It makes it very easy to install and edit custom products without worrying about user rights or identities.
3. To ZEO or Not to Zeo?
The Unified Installer will install Zope to either run in a Client/Server or stand-alone configuration. Here are the merits of each.
The Unified Installer offers two different strategies for your Zope configuration:
- A ZEO Client/Server configuration. ZEO (Zope Enterprise Objects) allows you to have several Zope clients processes (or separate servers) that share a common object database server process.
- A stand-alone Zope instance.
The stand-alone Zope instance is simpler to understand, integrate and control, and is probably the best choice for a simple or test environment.
The ZEO Client/Server configuration, though, has several advantages for production or development use:
- Better load balancing options. Even without a load-balancing proxy, running independent client and server processes can spread the load better on modern multi-core servers. With a load-balancing proxy, even better results are possible.
- The ability to run scripts against a live site. You may use "zopectl run" to run scripts on one of the clients while others serve the site to the Internet.
- Better debugging. You may run one client in debug mode while the rest run in production mode. You may then have improved diagnostics for the debug instance. You'll also be able to use introspection tools like Clouseau and "zopectl debug" against a live site.
- You may reserve a client for administrative access (it'll have its own port). Then, if you're slashdotted before you're ready, you'll be able to make changes via the administrative client even when your public client slows down.
4. Running the Unified Installer
Preparing to run and running the Unified Installer
Crank up your platform's package manager and make sure you've got the following installed:
- gcc, the GNU Compiler Collection.
- g++, the C++ extensions for gcc.
- GNU make, the fundamental build-control tool.
- GNU tar. This is the version of tar on all Linux, BSD and OS X platforms, but not Solaris.
- bzip2 and gzip
decompression packages. gzip is nearly standard; some platforms will require that bzip2 be installed.
Ideally, you should also have the libssl and readline libraries and development headers loaded (usually, the libssl-dev and readline-dev packages). These are not required, but add desirable functionality. libssl is required to use TLS with your mail server, which may be vital if it's not local. See the Unified Installer README.txt for details.
Now, choose a convenient working directory and unpack the .tar.gz archive (tarball) of the Unified Installer:
tar zxf Plone-VERSION-UnifiedInstaller.tar.gz
Then change into the newly created directory:
("VERSION-" will vary with release.)
If you've chosen to install with root privileges, either su to root or precede these commands with sudo.
Stand-Alone Zope Installation:
Then, sit back and watch the progress messages.
If the progress messages don't start, it will typically mean that a vital installation tool is missing. Use your package manager to install the tool, and try again.
If the installation succeeds, you'll see a set of instructions for starting your new Zope/Plone install. Make note of the password for the "admin" user. These instructions will also be available in README.txt file, and the pass word in "adminPassword.txt", in your new install.
If the installation should fail, don't panic. Make note of any error messages or diagnostics and, if you can't remedy the problem yourself, ask for help in the plone-setup mailing list or the #plone IRC channel. We'll need precise information about your platform and all possible diagnostic information to help. Also, make sure to check the Platform Notes section of the README.txt file included with the installer to see if there might be a work-around or special requirement note for your platform.
The install script creates a detailed log file, install.log, that may help diagnose an installation failure.
Checking your installation
If your installation succeeded, try starting it by following the instructions displayed at the end of the install process (or in the README.txt file in the install directory). Startup problems are uncommon, but do occasionally happen. The most common cause is that some other process has already claimed the 8080 port (or one or more of the 8100, 8080 and 8081 ports if you're using ZEO). You may wish to stop or kill the competing process if it's an old Zope/Plone installation. If not, you may reassign the ports used by your Plone installation by editing the buildout.cfg file and running bin/buildout to reassign ports.
If the start is successful, test your installation by opening a web browser and navigating to http://localhost:8080. (If you're testing on another machine, substitute your server host name for "localhost".)
You should see a Zope welcome message. A test Plone site should be available at http://localhost:8080/Plone, and the Zope Management Interface at http://localhost:8080/manage.
If Zope appears to be running, but you cannot connect, check to see if a firewall may be in place and blocking the connection.
5. Creating New Instances
The Unified Installer may be used to create additional Zope/Plone instances.
Once you have used the Unified Installer to build a complete Plone install, you may wish to create additional working instances to run other sites (or sets of sites). The Unified Installer makes it possible to set up new instances that will use the Python and Zope code base of your main install.
To install a new instance, first decide whether it will be a root or normal-user install. You may use the code base of a root-level install for a new root-level instance, or a non-root install for a new non-root instance. Also, the new instance may be a ZEO or stand-alone install, independent of the choice made for the main installation.
Change into the directory containing the install.sh file of your unpacked Universal Installer.
Precede the following commands by "sudo" or by using "su -" to switch to root
For a ZEO cluster instance:
./install.sh zeo --instance=new_instance_name
For a stand-alone Zope instance:
./install.sh standalone --instance=new_instance_name
new_instance_name should be a simple directory name -- not a full pathname. The new directory will be created as a new subdirectory of your full installation and will share its Python and buildout cache.
Setting New Ports
Your new instance isn't ready to run yet, because it's set to use the default ports and will conflict with the previous installation. Fortunately, that's easy to fix.
Change into the directory containing your new instance and open buildout.cfg with your favorite text editor.
If this is a standalone instance, you'll need to set a new port in just one spot:
http-address = 8080
There's a little more work for a ZEO instance. You'll need to change two http-address entries (one for each client) and the port for the ZEO server, which is set in the line:
zeo-address = 127.0.0.1:8100
Change only the port number (8100); leave the IP address alone.
Save your changes and run buildout to update all the parts of the installation:
If this is a root install, preface the command with "sudo" or use su to change to root.
You're now ready to run your new instance.
6. Command-Line Options
Some less commonly used Unified Installer options that may still be useful to you.
You may add the following options to your install.sh command line to more finely control your installation:
- Use to specify top-level path for installs. Plone instances and Python will be built inside this directory.
- In a root install, sets the effective user for running the instance. Default is 'plone'. Ignored for non-root installs.
- If you have an already built Python that's adequate to run Zope/Plone, you may specify it here.
virtualenv will be used to create an isolated Python environment for the installation. Your system's site library will not be touched. Python 2.4 is required for Plone 3.x, Python 2.6 for Plone 4.
Your Python must meet the needs of Plone, and the installer will test it for zlib, libssl and xml support before building for it.
- If not specified, a random password will be generated.
- SSL (usually OpenSSL) development libraries are needed to build a Python that will support SSL and TLS. Without it, Plone will be unable to use TLS in SMTP. The Unified Installer will ordinarily stop if it can't find the SSL headers and libraries. Use this option to tell the installer that you know what you're doing, and wish to proceed without SSL.
- lxml, a Python wrapper for libxml2 and libxslt, is not required for Plone 4.1. But it is needed by some popular addons like plone.app.theming. Unless you specify this flag, the installer will try to build lxml with static libxml2 and libxslt libraries. This may not work on all platforms.
- Skip running bin/buildout. You should know what you're doing. The main use for this option is if you want to use the Unified Installer to put all the pieces together, then plug in your own buildout.cfg.
The Unified Installer will try and figure out whether or not you have the libz, libjpeg and readline libraries on your system. If you do, great; if not, the installer will try to build them in the lib/ subdirectory of your installation target and link to them directly. This may not be what you want. If not, use the following command-line options to tune the behavior.
- to have this program determine whether or not you need the
library installed. If needed, will be installed to $PLONE_HOME. This is the default behavior.
- to force install to $PLONE_HOME (or $LOCAL_HOME) for static link -- even if a system copy of the library is available.
- to force no installation of the library.
7. Ubuntu / Debian Package Installation
How to install required packages on Debian/Ubuntu style systems.
This document has been superseded by http://docs.plone.org/manage/installing/requirements.html
Before installing you may install the needed system packages by running:
sudo apt-get install build-essential sudo apt-get install libssl-dev sudo apt-get install libxml2-dev sudo apt-get install libxslt1-dev sudo apt-get install libbz2-dev
sudo apt-get install zlib1g-dev
sudo apt-get install python-setuptools
sudo apt-get install python-dev
If you use Ubuntu Lucid or other older versions, please replace python-setuptools with python-distribute.
It's also very desirable to use system packages for common libraries, rather than to have the installer use its own:
sudo apt-get install libjpeg62-dev sudo apt-get install libreadline-gplv2-dev
sudo apt-get install python-imaging
And, if you want to enable Word and PDF document indexing:
sudo apt-get install wv sudo apt-get install poppler-utils
For more information about installing please read the manual on developer.plone.org
8. Platform Notes
User-contributed notes on using the Unified Installer on particular platforms
cat /etc/release Solaris 10 8/07 s10x_u4wos_12b X86
The install went smoothly, after the following 2 mods :
intall.sh line 1
from #! /bin/sh --> #! /bin/bash
install.sh line 81
from GNU_TAR=`which tar` --> GNU_TAR=`which gtar`