Installing Plone 3
From InstallationWiki
| Official Page |
| Project Documentation |
| Download |
|
Contents |
[edit] Installing on Windows
The Windows installer is an executable program that will install Python, Zope, and Plone. It sets up Plone to run as a service (meaning that it runs in the background) and includes a controller program to start and stop the service and perform major configuration.
[edit] Running the Windows installer
The Plone Windows installer you've downloaded should have a filename like Plone-3.2.0.exe. The filename will be specific to the Plone version, and may also include a build number for the installer version. Open this file to run the installer.
This should bring up a welcome screen. The Windows installer follows the standard Windows installer wizard format. You should click on Next to continue. The second page of the wizard will ask you to accept that Plone is licensed under the GNU Public License. Assuming you agree, click on the I accept the agreement option button and then click on Next. This will bring you to the following dialog box that allows you to specify the installation target directory:
If you're setting up a production server, there may be many considerations, such as drive speed and backup strategy, that go into selecting an installation target. For a test or development installation, though, the primary consideration is that there will be ample disk space to include both the installed components and your developing web sites. Click on Next once you've specified a target install directory, and you'll move into the administrative account setup dialog box.
You'll need to use the account name and password you specify here to do initial administration of your site, so make a note of them and click on Next to move to the options confirmation dialog box.
If your destination is correct, go ahead and click on the Install button to proceed. Expect the installation to take a substantial amount of time. Unlike some binary installers, the Plone Windows installer is not just extracting files into the target directory. Much of the install time will be spent using the newly-installed Python to compile Plone's libraries and Zope's libraries into efficient byte code. The installer also creates a Plone site object inside a new Zope database.
Go ahead and click on the Finish button once the installer finishes all that work.
[edit] Running Plone
Take a look, now, at your Windows Start | All Programs menu. There should be a new Plone item, containing several options.
The Plone shortcut, with Plone's three-dot logo, is the Plone controller, which you'll use to start, stop, and configure the Plone service. The Python item will open an interactive Python interpreter that you can use to explore Python. Links is a set of web links to convenient online resources.
The Development sub-menu has two very useful options:
Plone Debug: This runs Plone in a foreground console window in debug mode. Debug mode gives you advanced diagnostics, and can be particularly useful in tracking down why a particular add-on module won't load.
Setup Environment: This opens a Windows command-line console with environment variables set to point to your Zope/Plone install and its Python libraries. This helps you run Python scripts in an environment similar to the one used by Zope and Plone.
For starting and stopping Plone, you'll want to use the Plone controller application. Run it and you'll see the status of the Plone service, and a button that will allow you to start Plone (if it is not running already).
[edit] Setting ports
If you're running any other Internet services on the installation computer such as Microsoft's Internet Information Server (IIS), then before starting Plone, take a moment to check the port assignments. Click on the Ports item in the left pane. The right pane will then display the ports assigned to the Plone service.
As it is freshly installed, the Plone service will be set up to use port 80 for a Plone web site, port 8080 for the through-the-web Zope Management Interface, 21 for File Transfer Protocol, and 8280 for WebDAV. (FTP and WebDAV make it easy to move files in bulk into your Plone site; they are disabled by default, and you may ignore them unless you need them.)
Port 80 is the standard port for HTTP. If you already have a web server (such as IIS) running on the target computer, there is a very good chance that it's already using port 80. If so, you will need to choose an alternate port for the Plone web interface. Port 81 or 8081 might be a good choice.
|
Running IIS and Plone on the same ports is one of the most common installation mistakes on Windows. |
[edit] Starting and stopping the Plone service
After considering your port choices, click on Status in the left pane to return to the Status view. You may now start Plone by clicking the Start Plone button. This will take a moment, particularly the first time, but you will soon see the status indicator change to say Plone is running.
You may now use the Site Management buttons View Plone... or Zope Management Interface... to open web browser views of Plone or the ZMI. We'll talk about what to expect in the Testing Your Installation section following the platform-specific installer sections.
To stop Plone, click the Stop Plone button on the status pane.
[edit] Customizing startup
When you use the controller application to start and stop Plone, you are starting and stopping a service a program that runs as a background process with no window of its own. The controller starts, stops, and shows the status of the service, but it's otherwise not connected to it. After using the controller to start Plone, you may close the controller, and Zope/Plone will continue to run on your computer. This is typical for applications such as web servers that provide the Internet services.
The Plone Windows installer configures the Plone service to start automatically when you start your computer. This is reasonable for a server configuration, but may not be what you want if you're wanting to use your new Plone installation for testing or development.
To change the startup behavior of the Plone service, run the Windows Services administration tool (Start | All Programs | Administrative Tools | Services).
Look for Zope instance at ... at the end of the services list and double-click on it.
Startup type Automatic will cause the service to start automatically with the computer. Change it to Manual if you want to avoid this; you may then use the Plone controller to start and stop Plone.
[edit] The installation layout
When you installed Plone, the installer put both the programs and objects database into the target directory. Much of this is Python and Zope, and will not change as you update your site. The data subdirectory is where Plone itself, the add-on products, and the object database are installed. This is what the Plone documentation will often refer to as your Zope Instance.
[edit] Uninstalling
You can uninstall Plone by using the Windows Control Panel's Add or Remove Programs applet. Uninstalling Plone will leave your target directory in place, with the object database and custom products, untouched. Delete the directory manually if you no longer need these.
[edit] Installing on Mac OS X
The Plone installer for Mac OS X is available in two versions: one for each of the two processor families in use with OS X specifically, PPC, and Intel. Both may be downloaded from http://plone.org/products/plone. For recent vintage Macs, choose the Intel processor version. The installation procedure is identical for both.
The OS X installer makes great use of the Unix foundations of the operating system. It provides an easy-to-use graphical installer, but gives you all of the power of a Unix installation of Plone.
[edit] Running the installer
Download the OS X installer and you'll see that, like many OS X applications, it is distributed as a disk-image file. Double-click on the image file and OS X will effectively open a virtual disk drive.
The .mpkg file is the package installer; its name will vary with different versions of Plone. Double-click on it to start the actual install process.
In the first couple of installation steps, the installer will allow you to read the ReadMe.html file and ask you to confirm your agreement that Plone is distributed under the GPL. You'll then be offered a chance to choose an installation target drive.
[edit] Custom install options
The next step in the installation process gives you a choice of a standalone or ZEO cluster installation. The standalone installation is the simplest, and the best one to use for development purposes. The ZEO cluster installation offers opportunities for load balancing, and is better suited for production installs. Choose Production Mode to perform the installation as administrative user (you'll be asked for a password when the installation process runs). This will set up Zope to run under a special user identity with a security profile more appropriate for a production server.
Adding a startup item will up set your computer to start Plone whenever the computer starts.
[edit] Finishing up
You should be able to click through the rest of the installation process. At some point, you'll be required to enter a password for the Zope admin users.
When the install process finishes, open up a finder window and navigate to your Applications directory. You will discover a Plone folder.
This folder will include the components of Python and Zope, plus a zinstance (for standalone) or zeocluster (for ZEO cluster) folder that will contain the configuration files, the object database, and Plone itself.
[edit] Starting and stopping Plone
When you start or stop Plone, you'll actually be starting or stopping the Zope web applications server. To start Zope in a standalone installation, use the Plone Controller application to start, monitor, and stop Zope and Plone. For more complex installations, or if you just like to use the command line, open a terminal window with the Terminal application. Look for it via the finder in the Utilities folder, which is inside Applications. Then, issue the start command you found in the readme.txt file. Typically, it will look like this:
your-computer:~ stevemcmahon$ /Applications/Plone-3.1/zinstance/bin/plonectl start Password: . daemon process started, pid=15464
This starts Zope running as a service, independent of your terminal session, and you can then safely close the terminal application. Zope will keep running until you explicitly stop it, or until the computer is shut down. To stop Zope, use the terminal application again to issue the command line:
your-computer:~ stevemcmahon$ /Applications/Plone-3.1/zinstance/bin/plonectl stop
The command will vary with your Plone version. The adminPassword.txt file you found earlier is your guide to the exact command.
Also, it's handy to be able to start Zope in the foreground/debug mode:
your-computer:~ stevemcmahon$ /Applications/Plone-3.1/zinstance/bin/plonectl fg
If it is started in this way, Zope will stay connected to your terminal session and will print diagnostic messages to the terminal.
[edit] Uninstalling Plone
Removing a Plone install from OS X is easy. First, make sure that Zope isn't running; stop it if necessary. Then, use the Finder to delete the Plone-3.1## (the name will vary with your version) folder from the Applications folder.
[edit] Installing on Linux
Although it is offered under the title Get Plone for Linux/BSD/Unix, the Unified Installer is meant to install Plone on any Unix work-alike operating system. It's been tested on all of the common varieties of Linux, FreeBSD and OpenBSD, Mac OS X, and Solaris 10.
The Unified Installer is actually a source installation kit. It bundles together the source code for Plone and all of Plone's major dependencies, along with a shell script that builds and configures the components. Using it to install Plone is often as simple as downloading the kit, unpacking it, and issuing a single command. You will need to be comfortable with opening a terminal (or shell) session and issuing shell commands.
[edit] Installation options
The Unified Installer is versatile, and may be used to prepare Plone for use in configurations ranging from a production-ready, load-balanced cluster to a testing and development installation in a user home directory. As the latter requires no special privileges, and is easiest to understand, we'll cover it in this tutorial. However, you should know that you can also use the installer for more advanced installations. The installer's README.txt documents the advanced options.
[edit] Preparing your system
A few common development tools are required to use the Unified Installer. These may already be installed on your system, but if you've never built packages from source before, you may need to do some preparatory tool installation. In particular, you will need the GNU tools: GCC (GNU Compiler Collection), G++ (GNU C++), and make.
The simplest and quickest way to see if you already have these tools installed is to open a terminal window (or use SSH to open a remote shell, if it's not your workstation), and just try to run the commands gcc, g++, and make:
steve@ubuntu:~$ gcc gcc: no input files steve@ubuntu:~$ g++ g++: no input files steve@ubuntu:~$ make make: *** No targets specified and no makefile found. Stop.
If you receive a command not found response to any of these commands, use your platform's package manager to install the appropriate package. If you don't have root access on the install target, you'll need to contact your system administrator and ask them to install these common tools.
[edit] Extra packages
There are a few optional system library packages that you may want to install to add features. These include readline, libssl, libxml2, wv, and xPDF. These are mainly desirable for production servers. See the README.txt document file included with the Unified Installer for details of the roles played by these packages.
[edit] Downloading and unpacking the Unified Installer
Open a web browser and visit http://plone.org/products/plone. Copy the link location for Get Plone for Linux/BSD/Unix. Open a shell session on the installation target computer and download the Unified Installer to your home directory. wget is a handy tool for this.
steve@ubuntu:~$ wget http://plone.googlecode.com/files/Plone-3.1.0-UnifiedInstaller.tar.gz ... 09:57:51 (294.24 KB/s) - `Plone-3.1.6-UnifiedInstaller.tar.gz' saved [25236282/25236282]
Note the tar.gz filename extension of the file that you just downloaded. This is sometimes written .tgz and indicates a gzip compressed tar archive, sometimes called a tarball.
Now, unpack the archive by using the tar utility:
steve@ubuntu:~$ tar zxf Plone-3.1.6-UnifiedInstaller.tar.gz
Substitute the name of the installer that you have downloaded. Filenames will vary with Plone and installer versions.
This will create a Plone-3.1.6-UnifiedInstaller directory (the name will vary with the Plone version). In it, you should find a README.txt document, along with an install.sh script and package, and script subdirectories. It's always a good idea to take a moment to review the README.txt file.
[edit] Running the Unified Installer
Change your current directory to the newly-created installer directory:
steve@ubuntu:~$ cd Plone-3.1.6-UnifiedInstaller/
You're now ready to run the Unified Installer's install.sh script. Use the standalone command-line option to indicate that you want to create a simple Zope/Plone install:
steve@ubuntu:~/Plone-3.1.6-UnifiedInstaller$ ./install.sh standalone Stand-Alone Zope Instance selected Rootless install method chosen. Will install for use by system user steve ... Installing Plone 3.1.6 at /home/steve/Plone-3.1 ...
Now, sit back and watch the console messages stream by. The install script does a lot of work. In sequence, it will perform source installations of the following:
- Python
- PIL (the Python Imaging Library)
- ElementTree (a Python XML library)
- Python SetupTools
- Zope
- Plone
The install script may also install local copies of zlib (compression) and libjpeg (photographic image manipulation) libraries if you don't have development versions of these on the computer already. It will also initialize a Zope object database and create a Plone web site inside it.
Don't worry about the messages flying by. If any part of the install fails, the install script will stop and display an error message. When the process is complete, you can expect to see a concluding message containing an administrative password, start and stop instructions, and the success message:
... Plone successfully installed at /home/steve/Plone-3.1 See /home/steve/Plone-3.1/zinstance/README.txt for startup instructions
Make note of the administrative user name and password, then read the README.txt file in the zinstance directory for start and stop instructions. If you need to check your password again, you'll find it recorded in the adminPassword.txt file in the zinstance directory.
[edit] Starting and stopping Plone
You can now start Zope and Plone with the command line:
$HOME/Plone-3.1/zinstance/bin/plonectl start
Substitute the directory created by your installation for Plone-3.1; this will vary with Plone versions. $HOME is just shorthand for your home directory. A successful start will display a message like this:
. daemon process started, pid=15054 </pre> Where pid is the identifier for the process.
This starts Zope and Plone running in the background, detached from your shell session. You may close the Window or switch to some other work. Plone should keep running until you take action to stop it, or shut your computer down.
To check if Plone is running, use the command:
$HOME/Plone-3.1/zinstance/bin/plonectl status
And, to stop it, use the command:
$HOME/Plone-3.1/zinstance/bin/plonectl stop
In all of these cases, what you're actually starting and stopping is the Zope web application server. Plone is an application installed to run on Zope.
You may also find it very useful to be able to start Zope/Plone in foreground mode. In this mode, Zope will run in debug mode and will print diagnostic messages to the terminal window. You will not be able to run other programs in this shell session until you stop Zope, and if you close the terminal window, you will shut down Zope.
$HOME/Plone-3.1/zinstance/bin/instance fg
[edit] The installation layout
The installation process created a directory with a name such as Plone-3.1 in your home directory. This directory contains the Python and Zope builds and a zinstance directory that contains the configuration files, the object database, and a few utilities. zinstance is often referred to as your Plone instance directory.
[edit] Installation options
We briefly mentioned previously that the Unified Installer may be used to create different types of Plone installations. In particular:
- If you run the installer while logged in as root (or using the sudo command), Plone will be installed in your system's /usr directory, and will be set up to run under the plone user ID
- If you use the command-line option zeo rather than standalone, the installer will set up a Zope Enterprise Objects (ZEO) cluster configuration, which provides excellent load-balancing and control options
Both of these options are a good idea if your goal is a secure, robust install for a production server. Both add unnecessary complications, though, if you're only after a test or development installation.
[edit] Installation from source
The installers do a great job of installing and configuring Plone and the required components for you. So, why would you want to, or need to, install from source? Some reasons may be:
There's no installer for your platform, and no simple adaptation of the Unified Installer will work
- You may need to use an already-installed version of Python
- You may want to put the parts together yourself so that you can see how they really fit
- You may want to do some serious development work with Plone or may want to track cutting-edge development.
[edit] The software stack: Python, Zope, and Plone
Plone is built on the Zope web application server, which is largely written in Python, with some C language components. Plone is very picky about the versions of Zope that it runs on, and each Zope version, for its part, is very specific about its required Python version.
Plone 3.1.6, for example, requires Zope version 2.10.6. Later versions of Zope in the 2.10.x series are most likely to be acceptable. Zope 2.10.x runs under Python 2.4.5; later versions in the 2.4.x series are also likely to work.
The general strategy for a source installation is:
1. Install (or ensure that you have already installed) an acceptable version of Python.
2. Install the Python Imaging Library to work with the proper copy of Python.
3. Add the Python ElementTree library.
4. Install Zope with configuration instructions to use the proper copy of Python.
5. Create a working instance of Zope.
6. Install the Plone components into the working Zope instance.
[edit] Traditional source install
Traditionally, all of these steps are completed by visiting web sites, downloading the compressed archives (tarballs), unpacking, building, and testing, and then installing them. You may be able to take one big shortcut: download the Unified Installer for Linux, and use the contained packages for your builds. The install.sh script that the Unified Installer uses to build components is also a great source of practical hints for building components.
The most common mistake in traditional source installs is using the wrong copy of Python to build the components. Your system may have several versions of Python; you need to use only one of them, and that one must be compatible with the Zope version.
[edit] A better build with buildout
The Python, Zope, and Plone developer communities have been working on a better way of taking care of most of the steps for building Plone: using the zc.buildout Python library. You'll still need to build an appropriate Python installation yourself, but this is a particularly a good build method if your goal is to track Plone or advanced Plone product development, or to contribute to that development yourself.
[edit] Testing your installation
After you've installed and started Plone, you'll want to make sure it's working properly.
First, let's check the Zope web application server. Start up a web browser and navigate to http://localhost:8080/manage. If you've installed Plone on a remote server, replace localhost with the name or IP address of this server, for example, http://192.168.1.100:8080/manage.
You will be asked to authenticate. Use the administrative login ID (usually admin) and the password created during the installation. Then, you should see the Zope Management Interface (ZMI).
If your browser doesn't connect at all, first check to make sure that Zope is indeed running. If you've changed the port configuration for Zope, make sure that you've substituted your new port number for 8080. If Zope is running and the URL is correct, it is likely that a firewall (hardware or software) is blocking access to the Zope service. Check your firewall settings, or ask your firewall administrator to check them.
If the browser connects, but you can't authenticate, recheck your administrative login ID and password.
If you've successfully found the ZMI, look in the left pane for a Plone object. The Windows, Linux, and OS X installers should have created one for you. If you're installing from source, though, you'll need to add your own Plone site object. Look for the drop‑down selection next to the Add button and select Plone Site from the list. Click on the Add button and fill out the form to add a working site. Plone is probably a good choice for an initial identifier, if only to maintain some compatibility with the way the installers set it up.
After testing the ZMI, confirm that Plone is available by visiting http://localhost:8080/Plone (again, adjust for your host and port configuration). Expect to see an empty Plone site.
[edit] Additional References
- For instructions on customizing themes for Plone, click here
- For instructions on Installing Plone, click here
- For instructions on Customizing Plone 3, click here
- For instructions on Theming Plone Product, click here
[edit] Source
The source of this content is Chapter 2: Installing Plone 3 of Practical Plone 3: A Beginner's Guide to Building Powerful Websites by Jon Stahl, Martin Aspeli, David Convent, Darci Hanning, Ricardo Newbery, John DeStefano, Clayton Parker, Alex Clark, Veda Williams, Tom Conklin, Sam Knox, Steve McMahon, Matt Bowen (Packt Publishing, 2009).
