=========================== Plone 3.1 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, Zope and Python. Python is installed in a way that will not change or interfere with your system Python. This version includes Plone 3.1.1, Zope 2.10.5, and Python 2.4.4. New in this version: buildout is used to build Zope and Plone, making for easy updates and product installation. Paster and ZopeSkel are also installed as development tools. The Unified Installer was originally developed for Plone 2.5 by Kamal Gill. Adaptation to Plone 3.x and buildout: Steve McMahon (steve@dcn.org) Maintainer for Plone 3.x: Steve McMahon Feedback/bugs to: http://dev.plone.org/plone; component: Installer (Unified) *Important:* Back up your existing Plone site prior to running the installer or running buildout to update. Installation Instructions ========================= The installer will compile Python, Zope, and key required libraries from source. (Basic build tools and common libraries are required. See "Dependencies" and "Recommended Libraries" 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 may be acceptable for testing and development purposes. 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 a desktop-based development setup. For more detail on both root/non-root and ZEO/standalone choices, see "Installing Plone 3 with the Unified Installer":http://plone.org/documentation/tutorial/installing-plone-3-with-the-unified-installer in the Plone.Org documentation section. For a super-user (root) installation ------------------------------------ If you run the installation with root privileges, it will install Python/Zope/Plone to /opt/Plone-3.1 A "plone" user will be added, and Zope will be configured to run under that user id. You will need to start Zope as root or via sudo. To install Plone 3.1 in a stand-alone (single Zope instance) configuration: * cd to the installer directory and issue the following command: >> sudo ./install.sh standalone (or `su; ./install.sh standalone` on a sudo-less system) To install Plone 3.1 in a ZEO Cluster (ZEO server, 2 clients) configuration: * cd to the installer directory and issue the following command: >> sudo ./install.sh zeo (or `su; ./install.sh zeo` on a sudo-less system) 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-3.1 (the user's home directory, Plone-3.1 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 3.1 in a stand-alone (single Zope instance) configuration: * cd to the installer directory and issue the following command: >> ./install.sh standalone To install Plone 3.1 in a ZEO Cluster (ZEO server, 2 clients) configuration: * cd to the installer directory and issue the following command: >> ./install.sh zeo 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 /opt/Plone-3.1 for root install, $HOME/Plone-3.1 for non-root. --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. --user=user-name In a root install, sets the effective user for running the instance. Default is 'plone'. Ignored for non-root installs. --with-python=/full/path/to/python2.4 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. --password=InstancePassword If not specified, a random password will be generated. --libz=(local|global|no) Overrides the automatic determination of whether and where to install the libz compression library. --libjpeg=(local|global|no) Overrides the automatic determination of whether and where to install the libjpeg JPEG library. 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.1 ========================================== See UPGRADING.txt Dependencies ============ 1) gcc 2) g++ (gcc-c++) 3) GNU make 4) GNU tar 5) gunzip and bunzip2 6) posix-compliant /bin/sh Recommended Libraries and Utilities =================================== Install libraries prior to running installer. Development versions of some packages are required for headers. * libssl (SSL support) *Strongly recommended.* Used by openid and SecureMailHost; needed for https updates. libssl-dev * zlib (GZ compression) The Unified Installer will install this for you if necessary, but system libraries are usually preferable. zlib1g-dev * libjpeg (jpeg support) The Unified Installer will install this for you if necessary, but system libraries are usually preferable. libjpeg62-dev * readline (Python command-line history) libreadline5-dev readline-common * libxml2 (used by marshall) libxml-dev * wv (used to index Word documents) wv May be installed after Plone install. * xpdf (used to index PDFs) xpdf May be installed after Plone install. Install Location, Root Install ============================== - Base install at /opt/Plone-3.1 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 /opt/Plone-3.1/Python-2.4.4 - For ZEO Cluster - ZEO cluster (server and 2 clients) installed and configured at /opt/Plone-3.1/zeocluster Both --target and --name options may change this. - Add-on Products folder at /opt/Plone-3.1/zeocluster/products. (You may also install products via buildout.) - Data.fs (ZODB) at /opt/Plone-3.1/zeocluster/var/filestorage - adminPassword.txt at /opt/Plone-3.1/zeocluster/adminPassword.txt - For Stand-Alone: - Zope Instance installed and configured at /opt/Plone-3.1/zinstance Both --target and --name options may change this. - Add-on Products folder at /opt/Plone-3.1/zinstance/products (You may also install products via buildout.) - Data.fs (ZODB) at /opt/Plone-3.1/zinstance/var/filestorage - adminPassword.txt at /opt/Plone-3.1/zinstance/adminPassword.txt Install Location, Root-less Install =================================== - Base install at $HOME/Plone-3.1, 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-3.1/Python-2.4.4 - For ZEO Cluster - ZEO cluster (server and 2 clients) installed and configured at $HOME/Plone-3.1/zeocluster Both --target and --name options may change this. - Add-on Products folder at $HOME/Plone-3.1/zeocluster/products (You may also install products via buildout.) - Data.fs (ZODB) at $HOME/Plone-3.1/zeocluster/var/filestorage - adminPassword.txt at /opt/Plone-3.1/zeocluster/adminPassword.txt - For Stand-Alone: - Zope Instance installed and configured at /opt/Plone-3.1/zinstance Both --target and --name options may change this. - Add-on Products folder at $HOME/Plone-3.1/zinstance/products (You may also install products via buildout.) - Data.fs (ZODB) at $HOME/Plone-3.1/zinstance/var/filestorage - adminPassword.txt at $HOME/Plone-3.1/zinstance/adminPassword.txt Startup/Shutdown/Restart/Status instructions ===================================== Root Install ------------ Stand-Alone: To start Plone, >> sudo /opt/Plone-3.1/zinstance/bin/instance start To stop Plone, >> sudo /opt/Plone-3.1/zinstance/bin/instance stop To check status, >> sudo /opt/Plone-3.1/zinstance/bin/instance status ZEO Cluster: To start Plone, >> sudo /opt/Plone-3.1/zeocluster/bin/startcluster.sh To stop Plone, >> sudo /opt/Plone-3.1/zeocluster/bin/shutdowncluster.sh To restart Plone, >> sudo /opt/Plone-3.1/zeocluster/bin/restartcluster.sh To check status, >> sudo /opt/Plone-3.1/zeocluster/bin/clusterstatus.sh Root-less Install ----------------- Stand-Alone: To start Plone, >> $HOME/Plone-3.1/zinstance/bin/instance start To stop Plone, >> $HOME/Plone-3.1/zinstance/bin/instance stop To check status, >> $HOME/Plone-3.1/zinstance/bin/instance status ZEO Cluster: To start Plone, >> $HOME/Plone-3.1/zeocluster/bin/startcluster.sh To stop Plone, >> $HOME/Plone-3.1/zeocluster/bin/shutdowncluster.sh To restart Plone, >> $HOME/Plone-3.1/zeocluster/bin/restartcluster.sh To check status, >> $HOME/Plone-3.1/zeocluster/bin/clusterstatus.sh 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 Zope Management Interface at:: http://localhost:8080/manage And, your new Plone at:: http://localhost:8080/Plone (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. 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 Martin Aspelli's excellent tutorial "Managing projects with zc.buildout":http://plone.org/documentation/tutorial/buildout for information on buildout options. Apply settings by running bin/buildout in your buildout installation directory. Updating the installation ------------------------- To update your installation, backup and run: bin/buildout -n from your instance directory. This will bring your installation up-to-date, possibly updating Zope, Plone, eggs, and product packages in the process. (The "-n" flag tells buildout to search for newer components.) Check portal_migration in the ZMI after update to perform version migration if necessary. You may also need to visit the product installer to update product versions. Third-party products installed ============================== - PIL (Python Imaging Library) - libjpeg (JPEG library, usually installed to target/Python2.4/lib) - libz (compression, usually installed to target/Python2.4/lib) - libxml2-python (required for Marshall support) - Cheetah, Paste, PasteDeploy, PasteScript, ZopeSkel - The buildout recipe also installs elementtree 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. You may need to edit the install script to specify their locations and names. The install script tries to find zlib 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. Tested on the following operating environments ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ - Ubuntu 7.04, 7.10 Server - Mac OS X 10.4.x, 10.5.x (with Xcode tools; make sure to reinstall XCode when you upgrade to Leopard. On Leopard, it's strongly advised to install the MacPorts version of the readline library before running the Unified Installer.) - FreeBSD 6.1 (with addition of /opt directory for root install) - OpenBSD 4.2 (see note below) Previous 3-series Unified Installers were tested with the list below, and will probably work with them. - Ubuntu 6.06, 6.10 Server - Solaris 10 (edit install.sh to specify /bin/zsh or /bin/bash rather than /bin/sh; edit tool paths for GNU tools.) - Fedora Core 6 - Fedora 7 (64-bit PowerPC, x86_64) - SUSE LES 10 OpenBSD ~~~~~~~ The Unified Installer is not smart enough to install Python 2.4.x on OpenBSD; it just requires too many platform-specific patches. Alternatively, you may install for OpenBSD by preinstalling Python 2.4 packages, then telling the Unified Installer to use the preinstalled Python. Test builds on OpenBSD 4.2 succeeded with the following packages pre-installed: bzip2-1.0.4 block-sorting file compressor, unencumbered python-2.4.4p4 interpreted object-oriented programming language python-expat-2.4.4p4 expat module for Python If you are unable to install python-expat-2.4.4p4, you may need to install the xbase file set, which includes expat in some versions of OpenBSD (4.2). Then, when you run the Unified Installer, add the command-line argument: --with-python=/usr/local/bin/python2.4 Uninstall instructions ====================== 1) Stop Plone 2) Remove folder /opt/Plone-3.1 or $HOME/Plone-3.1 Backup instructions =================== 1) Stop Plone 2) Back up folder /opt/Plone-3.1 or $HOME/Plone-3.1 >> tar -zcvf Plone-3.1-backup.tgz /opt/Plone-3.1 Live backup is possible. See http://plone.org/documentation/how-to/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.4.4, placing it at /opt/Plone-3.1/Python-2.4 or $HOME/Plone-3.1/Python-2.4. Installer Bug reports ===================== Please use the Plone issue tracker at http://dev.plone.org/plone for all bug reports. Specify the "Installer (Unified)" component. Credits ======= 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 Alex Clark and Raphael Ritz for help with creation of a Plone site in the initial database. Thanks to the Davis (California) Plone Users Group for helping with testing. Thanks to Barry Page and Larry Pitcher for their work on the init scripts.