============================================ Installing Zope (for training purposes only) ============================================ ----------------------- A [not so] Quick Primer ----------------------- To deploy the WAeUP Student Registration Portal on your computer, you first have to set up a running Zope instance. These are installation instructions for Windows and Linux. Please note, that the recommended platform for production use is Linux due to advanced security and availability of service. However for testing you can freely use the operating system you like. General Remarks --------------- Any running Zope installation consists of at least an installed Zope binary and a Zope instance. It is important to distinguish Zope installations from Zope instances. Usually, you only have *one installation of a certain Zope version* installed (in case of WAeUP: version 2.9.3), while there might be *several Zope instances* installed based on the one Zope installation, but located at different locations in the filesystem. A special case, common on Windows but unusual on Unix-machines, is, to install an instance of Zope in the same directory, where the mean Zope installation is located. For the Zope-administrator it is then difficult to see a difference between the Zope installation and the Zope instance, but the difference indeed exists. Further complications arise from the fact, that the term 'install/start/stop/use Zope' often really means a Zope instance, but only speaks of 'Zope' in general. You might keep in mind, that after installing Zope instances and going into production use, you rarely handle with Zope installations, but mostly with Zope instances. The thing you start, when you start 'a Zope' is technically a Zope instance, which in turn deploys a Zope installation. Also the thing, which answers HTTP-Requests in a running 'Zope-System' is an Zope instance. Have a look at the following figure: .. image:: ./zinstancesetup.png *Fig. 1: Zope Overload* A (obviously overloaded) system with two Zope versions installed and five instances, which listen on five different ports. A browser is connected to port 8082, which is served by the 'waeup'-instance, which in turn deploys a Zope 2.9.3 installation (sharing it with two other instances). Installing Zope on Windows --------------------------- TODO Installing Zope on Linux ------------------------ Zope can be installed and instances be run by any user, who has access to the system. The highly recommended kind of Zope-install on Linux is to grab the source code and build the installation on your system directly. The install is not as complicated, as the length of this document might suggest. The length is a result of the authors logorrhoea, not of overwhelming complexity of the topic. If you are in a hurry and only want the short version, here are the essential steps. Log into your system as a normal user, go to your home directory and do: :: ~$ wget http://www.zope.org/Products/Zope/2.9.3/Zope-2.9.3.tgz ~$ mkdir -p zope/base zope/build zope/pkgs zope/instances ~$ cp Zope-2.9.3.tgz zope/build ~$ mv Zope-2.9.3.tgz zope/pkgs ~$ cd zope/build ~/zope/build$ tar -xzf Zope-2.9.3.tgz ~/zope/build$ cd Zope-2.9.3 ~/zope/build/Zope-2.9.3$ ./configure --prefix=/home/user/zope/base/2_9_3 ~/zope/build/Zope-2.9.3$ make ~/zope/build/Zope-2.9.3$ make install ~/zope/build/Zope-2.9.3$ /home/user/zope/base/2_9_3/bin/mkzopeinstance.py -d /home/user/zope/instances/myinstance1 -u user:secret ~/zope/build/Zope-2.9.3$ /home/user/zope/instances/myinstance1/bin/zopectl start *Fig. 2: Zope install on Linux / Short version* This should work on most systems. However, there are many error sources and if something goes wrong, you have to understand what is happening in each of steps. Explaining this is something, long versions are made for. 1. *Get the sources* Get the Zope sources from http://www.zope.org/. For the WAeUP-portal you currently need the 2.9.3 version of Zope, which can be found here: http://www.zope.org/Products/Zope/2.9.3/Zope-2.9.3.tgz Using the commandline you might change to your home directory ('cd') and do (the dollar-sign here and elsewhere denotes the commandline prompt, the tilde in front of the dollar sign means: 'home directory'): :: ~$ cd ~$ wget http://www.zope.org/Products/Zope/2.9.3/Zope-2.9.3.tgz --16:03:00-- http://www.zope.org/Products/Zope/2.9.3/Zope-2.9.3.tgz => `Zope-2.9.3.tgz' Resolving www.zope.org... 63.240.213.171 Connecting to www.zope.org|63.240.213.171|:80... connected. HTTP request sent, awaiting response... 200 OK Length: 8,010,113 (7.6M) [application/x-gzip] 100%[====================================>] 8,010,113 203.30K/s ETA 00:00 16:03:50 (156.42 KB/s) - `Zope-2.9.3.tgz' saved [8010113/8010113] 2. *Create a Zope directory tree* If you did not do already, it is adviceable to create a directory structure which enables you to find all your Zope installations and instances at a well defined place. Otherwise you might get lost in the many directories and subdirectories usually created by Zope. You can indeed use the tool of your choice for creating directories. For example the file-manager of your favourite window manager. Note however, that on many servers, you might going to administer on the internet later on, there is no such thing like a GUI installed (for good reason: GUIS on servers are unneccessary performance killers). I therefore, in the following example, show, how to create the directory structure on the commandline. We create the following directory structure: .. image:: ./zopedirtree1.png The directory tree contains a common subdirectory 'zope/' to keep all Zope related stuff apart from other user related data. It ends up in four leafs, which purposes are as follows: * *base/ -- The Zope installation directory* This directory holds the finished (compiled etc.) Zope installations (*not* the instances which have got their own directory). It will later on contain one subtree for each Zope version installed. * *build/ -- Helper directory for building Zope from source* This directory will be the place, where we start the installation. Its purpose is to have a place, where we can build (compile etc.) Zope, without having too much unused files laying around. Strictly speaking, after having built and installed Zope once, there is no need to keep the building directory and you might remove it afterwards. * *pkgs/ -- Repository for packages downloaded* Also this directory is not neccessary, to build Zope. It is a place to store packages, downloaded from the internet, especially Zope products or Zope source-tarballs. It comes in handy, if you want to keep packages for later use. We will use it to keep a backup of the Zope sources and CPS products, so we do not have to download them from internet everytime we create a new instance. * *instances/ -- The Zope instances directory* The most important directory in daily use. Here we create our Zope instances and here we will spend the most time, once, one or more insances are created and run. As you might already guessed, there is no need to create such a directory structure. Furthermore you can give the directories other names, whatever you like. In daily work it turned out, that such a directory tree is very handy and it tends to be a kind of best practice, to use it. On the commandline the directory tree is created like so: :: ~$ mkdir zope ~$ mkdir zope/base zope/build zope/pkgs zope/instances 3. *Unpack the sources* The sources are packed in a so-called 'tarball', which is denoted by the file extension 'tgz', a short form of 'tar.gz'. Now, as we freshly created a directory for building, we first copy the downloaded tarball containing the Zope sources to the build directory: :: ~$ cp Zope-2.9.3.tgz zope/build Afterwards we put the sources into the pkgs-directory to keep it for later use (and remove it from our home directory): :: ~$ mv Zope-2.9.3.tgz zope/pkgs The command 'mv' *moves* a file to a different location, thereby deleting the old file. Now we can change to the build-directory and unpack the sources: :: ~$ cd zope/build ~/zope/build$ tar -xzf Zope-2.9.3.tgz The commandline options 'xzf' mean: e(x)tract the file, un(z)ip the file and do the whole operation on the (f)ile Zope-2.9.3.tgz. This creates a new subdirectory 'Zope-2.9.3' with all required sources. 4. *Build Zope base* Change to the sources directory: :: ~/zope/build$ cd Zope-2.9.3 Here you can find a file configure, which is most important, to get all compile time options, supported by your Zope version. You can view them by calling './configure --help': :: ~/zope/build/Zope-2.9.3$ ./configure --help configure [--help] [--quiet] [--with-python=path] [--prefix=path] Create a Makefile suitable for building Zope Options: --help shows usage and quits --quiet suppress nonessential output --with-python specify a path to a Python interpreter to use --prefix specify an installation path for binary data Given no options, configure will search your PATH for a suitable Python interpreter and use '/usr/local/Zope-2.9.3' as a prefix. Basically, it tells you, that you can give a special Python version to build Zope and an installation path. Usually, it is best to let the configure script look for an appropriate Python interpreter. Note, that for building Zope you not only have to provide a running Python interpreter (preferably version 2.4.3), but also the header files and related developer files of your Python installation. Usually on Linux those packages are called python-dev or similar. The exact package name depends on your distribution. On Debian/Ubuntu based systems you can install the package 'python2.4-dev', which has to be done as superuser (denoted by the '#'-sign in the follwing): :: ~# apt-get install python2.4-dev While the Python developer files are rarely installed on usual end-user systems (except Zope users), the most systems already have a C-compiler (most common on Linx: gcc) installed, which you need too to build Zope. If Zope complains while building about unknown files or similar, make sure you have intalled the 'gcc' and the Python developer files. Consult your distributions' documentation to learn, how to do this. To start the real built, we give the 'configure'-script a prefix-option, which tells, that we want to have installed Zope in the base/ directory: :: ~/zope/build/Zope-2.9.3$ ./configure --prefix=/home/user/zope/base/2_9_3 Here we want Zope to be installed in /home/user/zope/base/2_9_3. Note, that the path /home/user/zope/base/ must already exist before executing the above command, while the subdirectory '2_9_3' (yes, its a diretory name) should be created by the build process. You can however use any name you want for your Zope installation, for example 'zope293' or something similar. Just change the prefix-parameter in that case accordingly. If everthing went well, you got the following (or similar) output: :: Configuring Zope installation Testing for an acceptable Python interpreter... Python version 2.4.3 found at /usr/bin/python The optimum Python version (2.4.3) was found at /usr/bin/python. In case of errors, you might provide a --with-python option. The Zope package is now configured and ready to be built. We start the process by doing: :: ~/zope/build/Zope-2.9.3$ make and, if everything worked fine: :: ~/zope/build/Zope-2.9.3$ make install The first step, the call of 'make', takes the biggest amount of time and is the crucial part of the whole installation process. The make command may raise some compiler warnings (complaining about eventually uninitialized variables), especially, if using the up-to-date version of gcc. You can safely ignore them. But if you get real error messages (not only warnings) something is seriously wrong and you have to resolve this problems before proceeding. In most cases it is a matter of (not) installed Python/gcc packages and depends on your system. There is a very high probability, that you can find some hints regarding your issues using Google or other internet ressources. If no serious errors occured: congratulations! You finally installed your first Zope. If you are short of disk space, you can now safely remove the complete directory tree in the 'build/' directory. All needed software is now installed in the base/ directory. 5. *Install a Zope instance* We can now change to our freshly created Zope installation: :: ~$ cd /home/user/zope/base/2_9_3 Instead of '2_9_3' you must use the name given to the prefix option of the 'configure'-script above. Here you can find some subdirectories of which for now only the bin-directory is of interest: :: ~/zope/base/2_9_3$ ls bin include lib skel zopeskel ~/zope/base/2_9_3$ cd bin ~/zope/base/2_9_3/bin$ ls analyze.py fstail.py requestprofiler.py zeoctl.py checkbtrees.py fstest.py runzeo.py zeopack.py check_catalog.py load_site.py simul.py zeopasswd.py compilezpy.py migrate.py space.py zeoqueue.py copyzopeskel.py mkzeoinstance.py stats.py zeoreplay.py copyzopeskel.pyc mkzeoinst.py test.py zeoserverlog.py decompilezpy.py mkzopeinstance.py timeout.py zeoup.py fsdump.py netspace.py zconfig zodbload.py fsoids.py parsezeolog.py zconfig_schema2html zopetest fsrefs.py reindex_catalog.py zdctl.py zpasswd.py fsstats.py repozo.py zdrun.py Almost all of these files are executables, i.e. programs, you might need in your further work with Zope. Most Zope administrators, however, know only the script 'mkzopeinstance.py', which creates a new Zope instance. We will use it too. First we call it with the '--help' option, to see, what the script can do for us: :: ~/zope/base/2_9_3/bin$ ./mkzopeinstance.py --help mkzopeinstance.py: Create a Zope instance home. usage: mkzopeinstance.py [options] Options: -h/--help -- print this help text -d/--dir -- the dir in which the instance home should be created -u/--user NAME:PASSWORD -- set the user name and password of the initial user -s/--skelsrc -- the dir from which skeleton files should be copied When run without arguments, this script will ask for the information necessary to create a Zope instance home. Note: On UN*X systems the '--help' switch is very common. Most programs support it. The help message displayed tells us, that we can name a directory to specify, where the instance should be created and a username/password pair for the initial login. That is, what we are going to do. As path for the instance we choose a (yet not existing) directory in the 'instances'-directory, say 'myinstance1'. The user/password values for our first local tries can be kept simple: :: ~/zope/base/2_9_3/bin$ ./mkzopeinstance.py -d /home/user/zope/instances/myinstance1 -u user:secret This takes only about one second. If you do not give a username and password via parameters, you will be prompted for the data. 6. *Configure and start your new instance* Change to the instances directory, to see, whether your new Zope instance was created: :: ~$ cd /home/user/zope/instances ~/zope/instances$ ls myinstance1 Okay, the instance exists, so go in and have a look: :: ~/zope/instances$ cd myinstance1 ~/zope/instances/myinstance1$ ls bin etc Extensions import inituser lib log Products README.txt var Here we see the main directories for the further work with Zope. The most important directories: * *bin -- Executables to start/stop your instance* This directory contains the programs to start or stop your Zope instance. You can do much more with them, but we refer to the extended possibilities later on. * *etc -- Configuration of your instance* This directory holds the important configuration file of your Zope instance. Chances are, that you do not need to change the default configuration, but we will take a look into it anyway. * *log -- Logfiles of your instance* Here you can find the logs of your instance. Namely the access logfile 'Z2.log' and an error log called 'event.log'. The event log saves all Zope specific events, not only errors. * *Products -- 3rd-party products repository* Here can install all products, like CPS or the WAeUP SRP product. They are generally installed on a per-instance basis. * *var -- The data directory* In this directory will Zope save all runtime information, i.e. the Z Object DataBase (ZODB) and other temporary data. The ZODB will be held in a file called Data.fs, which contains all the data you entered into the running Zope system. If it gets corrupted, the whole instance is lost. In special cases (ZEO setup etc.) the Data.fs can be shared amongst several Zope instances and reside at another place. Before starting the instance, first have a look at the configuration file 'zope.conf' which can be found in the etc-directory of your instance. With growing version numbers of Zope also the Zope configuration file grows larger and larger. For version 2.9.3 there are too many options available in zope.conf, to discuss every single option herein. One option, however, is of special interest: the port number, where the Zope instance will listen to requests. 'zope.conf' is a simple plain text file, which you can edit with any text editor (please do not use something like OpenOffice or Word to edit a plain text file: it won't be plain text any more). To view its content you can use the command 'less' on UN*X. In the zope.conf you will find (near the end of file) a section called 'http-server', which looks like this: :: # # An HTTP server starts on port 8080. # valid keys are "address" and "force-connection-close" address 8080 # force-connection-close on This means, Zope will listen on port 8080. This is okay, if there is no other process still listening on port 8080 (note for geeks: you can use the 'netstat' tool to check, which ports are already in use). But if you want to run several Zope instances in parallel, you must set the listening port to another value. We assume, port 8080 is not in use and simply start the Zope instance in the foreground for the first time: :: ~/zope/instances/myinstance1$ ./bin/runzope You will get some DeprecationWarnings and a message about a installed sighandler. This means, Zope has started and you should be able to use your Browser and browse to http://localhost:8080/ Note the portnumber in the URL: .. image:: ./snapshot1.png If you can see the Zope Quick Start screen, everything is fine and you can stop the Zope instance on the console by typing CTRL-C. We used the 'runzope' script to start Zope in the foreground. This is a recommended way to start freshly created instances, because problems occurring during the startup process will be displayed directly on the screen (in the shell). For long-term use this is not an option, because you want to run Zope as a server, which runs in the background and continues to run, when you log out. To start Zope in background use the 'zopectl' command. It requires a parameter, which specifies the action to be taken: :: zopectl start|stop|restart There are other possible actions as well, but for the beginning we start with 'start': :: ~/zope/instances/myinstance1$ ./bin/zopectl start . . . daemon process started, pid=457 You now have Zope running in regular mode. Check it by visiting the Quick Start Page. If everything went fine, you can see the startup messages in the logfiles in the log directory of your instance. You can also enter the Zope Management Interface (ZMI), by adding '/manage' to the URL: http://localhost:8080/manage This requires to enter the credentials, you gave during installation of the instance. .. image:: ./snapshot2.png After successfull authorization you should be able to see the ZMI: .. image:: ./snapshot3.png That's it. You installed Zope successfully. Congratulations! To stop your running instance, you can go to the control panel in the ZMI and shutdown by mouse-click, or, on the commandline, do :: ~/zope/instances/myinstance1$ ./bin/zopectl stop You can play a bit with your instance and then try to do the other steps to run a fully working version of the WAeUP SRP. *Have fun!* *Uli Fouquet*