============================== Plone 4.0.4: 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 4.0.4, Zope 2.12.14, and Python 2.6.6. 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. Outline of this document ------------------------ Installation Instructions For a super-user (root) installation For a non-super-user (rootless) installation Installation Options Dependencies Recommended Libraries and Utilities Install Location, Root Install Install Location, Root-less Install Startup/Shutdown/Restart/Status instructions Root Install Root-less Install Ports Post-installation Instructions Root Install Notes Updating After Installation Customizing the installation Third-party products installed Platform Notes Mac OS X Server Solaris OpenBSD/NetBSD Uninstall Instructions Backup Instructions Coexistence with System Python Developer Options Installer Bug reports Credits 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 /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.] 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 4.0.4 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 4.0.4 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 (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.0.4 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.0.4 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 /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. --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.6 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=(auto|yes|no) Overrides the automatic determination of whether and where to install the libz compression library. --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 openssl development libraries. SSL may not be needed in simple environments. 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 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. Debian/Ubuntu package names are included below. * 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. * 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.6 - 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.6 - 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 ------------ Stand-Alone: To start Plone, >> sudo /usr/local/Plone/zinstance/bin/plonectl start To stop Plone, >> sudo /usr/local/Plone/zinstance/bin/plonectl stop To check status, >> sudo /usr/local/Plone/zinstance/bin/plonectl status ZEO Cluster: To start Plone, >> sudo /usr/local/Plone/zeocluster/bin/plonectl start To stop Plone, >> sudo /usr/local/Plone/zeocluster/bin/plonectl stop To restart Plone, >> sudo /usr/local/Plone/zeocluster/bin/plonectl restart To check status, >> sudo /usr/local/Plone/zeocluster/bin/plonectl status Root-less Install ----------------- Stand-Alone: To start Plone, >> $HOME/Plone/zinstance/bin/plonectl start To stop Plone, >> $HOME/Plone/zinstance/bin/plonectl stop To check status, >> $HOME/Plone/zinstance/bin/plonectl status ZEO Cluster: 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 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 a specific user id. 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. 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. Third-party products installed ============================== - PIL (Python Imaging Library) - libjpeg (JPEG library, usually installed to target/Python2.6/lib) - libz (compression, usually installed to target/Python2.6/lib) - libxml2-python (required for Marshall support) - libreadline (terminal mode command-line and prompt editing) - 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 your shell paths or set compile or link flags in some environments to make sure you use the GNU tools.. The install script tries to find zlib, 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 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. Solaris (need further check) ~~~~~~~~~~~~~~~~~~~~~~~~~~~~ If you want to compile Python 2.6 and so on with Sun cc other than GNU cc, you have to set an environmental variable CC=/your/Sun/cc. OpenBSD/NetBSD ~~~~~~~~~~~~~~ The Unified Installer is not smart enough to install Python 2.6.x on OpenBSD/NetBSD; it just requires too many platform-specific patches. Alternatively, you may install for OpenBSD by preinstalling Python 2.6 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.6.6 interpreted object-oriented programming language python-expat-2.6.6 expat module for Python If you are unable to install python-expat-2.6.6, 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.6 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 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.6.6, placing it at /usr/local/Plone/Python-2.6 or $HOME/Plone/Python-2.6. 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. 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 ======= 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.