The basics of installing Plone on Windows, OS X, Linux, *BSD and nearly every other platform.
1. Installation Quick Guide
How to install Plone on your box, step by step. Short version.
Before installing Plone on Linux, BSD or other Unix-like operating systems, you should make sure that you have the following packages installed:
gcc, a C compiler
g++, software to extend gcc to compile C++ code
GNU make, a compilation tool
GNU tar, package for creating tar archives
bzip2 and gzip decompression packages
The following packages are also recommended, although they aren't needed to build Plone
libssl, a package that allows the use of TSL with your mail server.
readline, a GNU package that increases the ability of applications to edit terminal commands.
Getting the Plone Installer
The installer for Linux/BSD/Unix, called the Unified Installer, can be downloaded from this page of the Plone website.
- Click on the Download Plone button and you will be taken to page that lists the various installers for Plone.
- Click on the link for the Unified Installer to begin downloading Plone.
- After it has finished downloading, open up a terminal and change directories to where the installer file you downloaded is located.
- Extract the installer by typing "tar xzf InstallerName ", where InstallerName is the name of the Plone Installer you downloaded.
- In your command prompt enter the directory of the folder you just extracted.
Configuring your Plone installation
The first thing you must decide when installing Plone is decide whether you would like a ZEO or a standalone installation. You should probably use ZEO if you are going to be using Plone for any production. However, if you are just testing out Plone or are going to use it for development, the standalone option would be best. For a more in-depth discussion read this section.
To initiate the installation type "./install.sh method" where method is either "standalone" or "zeo".
Installing as standalone, non-root Plone user
This is recommended method if you are installing Plone for the first time and your site is lightweight.
Installing as root
This is not recommended unless you know what you are doing.
If you would like to install Plone in server mode type "sudo ./install.sh method" or run the installation script as root some other way. A complete list of command-line options can be found here.
Near the end of the installation, the installer should have printed out the default username and password for your Plone installation to the terminal. If you have trouble finding them, they are also listed inside of a text file called adminPassword.txt (which can be found in the zinstance or zeoserver folder (depending on whether you ran the unified installer with "standalone" or "zeo" option) of your Plone installation).
To start Plone:
- "cd" to your Plone install directory.
- Enter your zope instance folder.
- Execute "./bin/plonectl start". (The port Plone uses may be adjusted in buildout.cfg and then running "/bin/buildout").
- Browse to your instance by visting http://localhost:8080 in your web browser. If you specified another port, use it instead of 8080.
- Click on "Create a new Plone site" and enter your login information to start using Plone. Enter in the requested information and then submit the form to finish the creation of your site. You can find your site at http://localhost:8080/SiteName, where "SiteName" is the Id of your Plone site.
To stop the Plone process run "./bin/plonectl stop". Have fun using Plone!
If you want to use Plone on a desktop Mac, the OS X binary installer is a good choice. It uses the OS X installer and provides a visual controller. However, since it provides pre-compiled binaries, it's very hard to add new components that require binary builds. If you need to do that, add XCode to your system and use the Unified Installer.
Windows (2000, 2003, XP, Vista, 7)
You can download Plone for Windows from this page.
- Click on the Download Plone button.
- Click on the link for the Windows Installer and save it to a memorable location like your Desktop.
- Double-click the installer file to initiate the installation process.
The Plone Installation Wizard
- Enter the directory where you would like to install Plone to. For most people, the default entry should be fine.(Click "Next" after each step to continue)
- Enter in your desired username and password for the administrator account.
- Review the current configuration options.
- During the installation a progress bar will show how close the installer is to completion. Mark the check boxes to show whether you would like to add Plone as a service so that it will automatically run at startup.(Note: This can be changed at any time by running "bin\instance.exe remove" from your install directory) or if you would like to run Plone after exiting the installer.
Starting up Plone
If you decided not to make Plone a service you can start and stop your Plone instances by going to your Plone directory in your command line and executing:
or by using the Plone Controller GUI.
The Plone Controller can be found in your menu at Start → All Programs → Plone → Plone Controller. It is used to edit Plone's settings and to start or stop Plone. If you decide that you want to make Plone a service execute:
Likewise, to unistall Plone execute:
Once you have started an instance of Plone, you can view it by visiting http://localhost:8080 in your web browser. If it won't load, make sure that your firewall hasn't blocked the TCP port 8080.
Click on "Create a new Plone site" and enter your login information to start using Plone. Enter in the requested information and then submit the form to finish the creation of your site. You can find your site at http://localhost:8080/SiteName, where "SiteName" is the Id of your Plone site. Have fun with Plone!
2. Installing on Linux / Unix / BSD
The Unified Installer is a source-distribution kit that includes nearly everything necessary to build Plone on Linux, OS X, BSD and most Unix workalikes
2.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.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.
2.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.
2.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.
2.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.
2.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.
2.7. Ubuntu / Debian Package Installation
How to install required packages on Debian/Ubuntu style systems.
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
2.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`
3. Installing on Windows
How to get Plone up and running on Windows, not for serious development
The binary installer for Windows is the option to choose if you want to try out Plone on Windows or host a site but not serious development. Should you want to do serious development, check this document.
This document was updated for Plone-4.1.2.
This section explains how to do a basic installation of Plone.
Downloading and Installing Plone
- Download the installer from this page on plone.org: http://plone.org/download.
- Save it in a place you can remember, such as your Desktop.
- After the download is completed, double-click on the installer file to run it.
- Go through the installation wizard. The installer creates a folder in C:\Plone41 and installs Plone there.
- Wait while the installer extracts files and sets up your Plone instance.
- The newer installer automatically installs Windows services for Plone and starts the services so there's no need to start Plone by hand. If you need to start or stop the new services they are called "Plone 4.1" and "Plone 4.1 Zeo" and are listed in the Services controller window.
Note: You may need to tell your firewall to open TCP Port 8080 before you can access Plone's web interface.
- Open a browser window and browse to http://localhost:8080 and click the "Create a new Plone site" button.
- You'll be asked to login next. The default username is "admin" and the password is also "admin" (no quotes).
- On the "Create a Plone site" page scroll down and click the "Create Plone Site" button.
- After the site is created you'll be redirected to the site at http://localhost:8080/Plone. You can use this URL the next time you want to visit your site.
Starting and Stopping Your Plone Services
In case you need to stop or start your Plone services by hand you can access them this way:
Click on the Windows "Start" button.
Type "services" (no quotes) into the search bar that will appear at the bottom of the Start Menu.
Click on the entry called "Services" in the "Programs" category of the search results.
In the Services window, scroll down to find the "Plone 4.1" and "Plone 4.1 Zeo" services.
From here you can start and stop the services whenever you need to.
If you're only testing Plone and you don't want it to start every time you start your computer, adjust the "Properties" of each of the Plone services and set the "Startup Type" to "Manual."
This section give more information about the Windows installer and how to customize it if needed.
As of Plone 4.0.9 and Plone 4.1 there are new Windows installers being provided to the community. These installers behave differently than previous versions. This document explains the changes and the rationale behind them.
Previously the Plone Windows installer ran buildout after allowing the user to input several variables, including an installation directory. However, due to the way that Python, Windows and buildout interact, long or complex installation directories did not always work, leading to fatal errors during the buildout installation process. This failure would be very difficult for an evaluator to recover from, thereby creating a bad “first impression” for a new user.
The new Plone Windows installer trades off some of this flexibility for vastly improved reliability. Buildout is run when building the installer, not “live” during the installation process. This means that buildout can never fail during installation. However, this also means that the Windows installer will only install Plone into C:\Plone41 (for 4.1) and C:\Plone42 (for 4.2).
For users who require more flexibility in installation paths, we have provided the ability to copy-and-paste an installation directory to a new location, as well as a new facility to create custom Windows installers for Plone (which ships with the Plone Windows installer). Now, you can modify your buildouts and regenerate new Windows installers with different configurations (e.g., using multiple ZEO clients, multiple databases or different products), which you can use in production or distribute to customers.
Plone’s Windows services now use a recipe called enfold.recipe.winservice which is a fork of the z3c.winservice recipe for use in Zope 2. The new Plone Windows installer has three key differences from previous versions:
- Default credentials for Plone
- Previously you could create these from inside the installer.
- Now it is hardcoded as login: admin and password: admin. This makes the Windows installer consistent with the Unified Installer and the Mac OS X installer.
This can be changed by editing buildout.cfg, see the [shared] section
which contains the line: user = login:password
- Windows Service name
- Previously this was auto-generated during installation
- Now it is defined in buildout.cfg see the [service] and [service-zeo] sections
name = Unique Service Name
- Installation Location
- Previously the user could select/create new folder to install Plone
- Now it installs into C:\Plone41 or C:\Plone40 (depending on version)
How to Change the Installation Location
The new Plone Windows installer does not allow you to change the installation location when you run the installer. However, it is still possible to install Plone into a different location after the initial installation, albeit via a more manual process. For example, suppose you have installed Plone into C:\Plone41 and after evaluation you want to copy it to a more permanent location, lets say Z:\Plone41-Intranet\.
The good news is that your installation directory, C:\Plone41, is 100% self-contained. There are no external dependencies defined anywhere else. You can simply copy/paste this directory, modify your buildout.cfg file (described below), and rebuild your custom environment. For a production-quality deployment of Plone, you will nearly always need to do this because the default settings for Plone Windows installation are very basic, and intended more for evaluation than for production deployment scenarios.
Here’s a simple example for moving Plone from its default installation directory (C:\Plone41) to a new directory, Z:\Plone41-Intranet
- Change to Z:\ drive
- mkdir Plone41-Intranet
- cd Plone41-Intranet
- copy C:\Plone41\* .
- switch to Z:\Plone41-Intranet
- edit the buildout.cfg file
- goto [shared] section
- change user variable to login:password they want to use
- change the http-address to a unique port, say 9090
- change the zeo-address to a unique port, say 9999
user = administrator:s3kr1t
http-address = 9090
zeo-address = 9999
debug-mode = off
verbose-security = off
- goto [service] section
- change name variable to “Plone 4.1 Intranet”
recipe = enfold.recipe.winservice:service
name = Plone 4.1 Intranet
runzope = run-instance
- goto [service-zeo] section
- change name variable to “Plone 4.1 Intranet Database”
recipe = enfold.recipe.winservice:service
name = Plone 4.1 Intranet Database
runzope = run-zeo
- re-build the configuration files
Your terminal will be connected to the server. If it says “Zope Ready to Serve Requests” you are good to go. Control-C or Break out of it and start the service from services panel or command line
I believe there is a problem with registry and python. Since we *do not* register the python system-wide you will need to have your current working directory as Python. So the command will be as follows:
Z:\Plone41-Intranet> cd python
Z:\Plone41-Intranet\Python> python ..\bin\service.py --startup auto install
Z:\Plone41-Intranet\Python> python ..\bin\service-zeo.py --startup auto install
Building a Custom Windows Installer
The biggest feature of the new installer is the ability to create a custom Windows installers, which you can use or distribute. Previously, building a custom Windows installer required substantial knowledge of how many different sub-systems work together. Now you simply edit the installer.cfg buildout recipe. Re-run buildout with -c installer.cfg and you will get a new Windows installer executable in the current working directory.
See the “Windows Packaging Details” link below for more information.
- Windows Packaging Details - http://package.enfoldsystems.com/docs/windows.html
- Buildout website - http://www.buildout.org/