source: WAeUP_Doc/ExtendedInstructions/1InstallingZope.rst @ 4639

Last change on this file since 4639 was 3860, checked in by hraban, 16 years ago

trying to update docs to versions in use

File size: 22.8 KB
RevLine 
[1617]1============================================
2Installing Zope (for training purposes only)
3============================================
4-----------------------
5A [not so] Quick Primer
6-----------------------
7
8To deploy the WAeUP Student Registration Portal on your computer, you
9first have to set up a running Zope instance. These are installation
10instructions for Windows and Linux. Please note, that the recommended
11platform for production use is Linux due to advanced security and
12availability of service. However for testing you can freely use the
13operating system you like.
14
15General Remarks
16---------------
17
18Any running Zope installation consists of at least an installed Zope
19binary and a Zope instance. It is important to distinguish Zope
20installations from Zope instances. Usually, you only have *one
21installation of a certain Zope version* installed (in case of WAeUP:
[3860]22version 2.9.8), while there might be *several Zope instances* installed
[1617]23based on the one Zope installation, but located at different locations
24in the filesystem.
25
26A special case, common on Windows but unusual on Unix-machines, is, to
27install an instance of Zope in the same directory, where the mean Zope
28installation is located. For the Zope-administrator it is then
29difficult to see a difference between the Zope installation and the
30Zope instance, but the difference indeed exists.
31
32Further complications arise from the fact, that the term
33'install/start/stop/use Zope' often really means a Zope instance, but
34only speaks of 'Zope' in general. You might keep in mind, that after
35installing Zope instances and going into production use, you rarely
36handle with Zope installations, but mostly with Zope instances. The
37thing you start, when you start 'a Zope' is technically a Zope
38instance, which in turn deploys a Zope installation. Also the thing,
39which answers HTTP-Requests in a running 'Zope-System' is an Zope
40instance. Have a look at the following figure:
41
42  .. image:: ./zinstancesetup.png
43
44*Fig. 1: Zope Overload*
45
46A (obviously overloaded) system with two Zope versions installed and
47five instances, which listen on five different ports. A browser is
48connected to port 8082, which is served by the 'waeup'-instance, which
[3860]49in turn deploys a Zope 2.9.8 installation (sharing it with two other
[1617]50instances).
51
52
53Installing Zope on Windows
54---------------------------
55
56TODO
57
[3860]58Installing Zope on MacOS X
59--------------------------
60
61Mostly the same as on Linux (see below).
62
63  * Your home directory (~) is `/Users/user`.
64 
65  * You need to install Developer Tools (XCode).
66 
67  * You need to install wget on your own (perhaps use MacPorts or Fink) or use curl.
68 
69  * Depending on your OS version you need to install an older Python version,
70    perhaps via MacPorts or Fink.
71    (*Don't touch Apple's default Python installation!*)
72
[1617]73Installing Zope on Linux
74------------------------
75
76Zope can be installed and instances be run by any user, who has access
77to the system. The highly recommended kind of Zope-install on Linux is
78to grab the source code and build the installation on your system
79directly.
80
81The install is not as complicated, as the length of this document
82might suggest. The length is a result of the authors logorrhoea, not
83of overwhelming complexity of the topic.
84
85If you are in a hurry and only want the short version, here are the
86essential steps. Log into your system as a normal user, go to your
87home directory and do:
88
89  ::
90
[3860]91    ~$ wget http://www.zope.org/Products/Zope/2.9.8/Zope-2.9.8-final.tgz
[1617]92    ~$ mkdir -p zope/base zope/build zope/pkgs zope/instances
[3860]93    ~$ cp Zope-2.9.8-final.tgz zope/build
94    ~$ mv Zope-2.9.8-final.tgz zope/pkgs   
[1617]95    ~$ cd zope/build
[3860]96    ~/zope/build$ tar -xzf Zope-2.9.8-final.tgz
97    ~/zope/build$ cd Zope-2.9.8-final
98    ~/zope/build/Zope-2.9.8-final$ ./configure --prefix=/home/user/zope/base/2_9_8
99    ~/zope/build/Zope-2.9.8-final$ make
100    ~/zope/build/Zope-2.9.8-final$ make install
101    ~/zope/build/Zope-2.9.8-final$ /home/user/zope/base/2_9_8/bin/mkzopeinstance.py -d /home/user/zope/instances/myinstance1 -u user:secret
102    ~/zope/build/Zope-2.9.8-final$ /home/user/zope/instances/myinstance1/bin/zopectl start
[1617]103
104  *Fig. 2: Zope install on Linux / Short version*
105
106This should work on most systems. However, there are many error
107sources and if something goes wrong, you have to understand what is
108happening in each of steps. Explaining this is something, long
109versions are made for.
110
111
112  1. *Get the sources*
113
[3860]114     Get the Zope sources from `http://www.zope.org/`. For the
115     WAeUP-portal you currently need the 2.9.8 version of Zope, which can
116     be found here: `http://www.zope.org/Products/Zope/2.9.8/Zope-2.9.8-final.tgz`
[1617]117
[3860]118     Using the commandline you might change to your home directory (`cd`) and
[1617]119     do (the dollar-sign here and elsewhere denotes the commandline
120     prompt, the tilde in front of the dollar sign means: 'home directory'):
121
122       ::
123
124         ~$ cd
[3860]125         ~$ wget http://www.zope.org/Products/Zope/2.9.8/Zope-2.9.8-final.tgz
126         --16:03:00--  http://www.zope.org/Products/Zope/2.9.8/Zope-2.9.8-final.tgz
127               => `Zope-2.9.8-final.tgz'
[1617]128         Resolving www.zope.org... 63.240.213.171
129         Connecting to www.zope.org|63.240.213.171|:80... connected.
130         HTTP request sent, awaiting response... 200 OK
131         Length: 8,010,113 (7.6M) [application/x-gzip]
132
133         100%[====================================>] 8,010,113    203.30K/s    ETA 00:00
134
[3860]135         16:03:50 (156.42 KB/s) - `Zope-2.9.8-final.tgz' saved [8010113/8010113]
[1617]136
137
138  2. *Create a Zope directory tree*
139
140     If you did not do already, it is adviceable to create a directory
141     structure which enables you to find all your Zope installations
142     and instances at a well defined place. Otherwise you might get
143     lost in the many directories and subdirectories usually created
144     by Zope.
145
146     You can indeed use the tool of your choice for creating
147     directories. For example the file-manager of your favourite window
148     manager. Note however, that on many servers, you might going to
149     administer on the internet later on, there is no such thing like
150     a GUI installed (for good reason: GUIS on servers are
151     unneccessary performance killers). I therefore, in the following
152     example, show, how to create the directory structure on the
153     commandline.
154
155     We create the following directory structure:
156
157     .. image:: ./zopedirtree1.png
158
159     The directory tree contains a common subdirectory 'zope/' to keep
160     all Zope related stuff apart from other user related data. It
161     ends up in four leafs, which purposes are as follows:
162
163       * *base/ -- The Zope installation directory*
164
165         This directory holds the finished (compiled etc.) Zope
166         installations (*not* the instances which have got their own
167         directory). It will later on contain one subtree for each
168         Zope version installed.
169
170       * *build/ -- Helper directory for building Zope from source*
171
172         This directory will be the place, where we start the
173         installation. Its purpose is to have a place, where we can
174         build (compile etc.) Zope, without having too much unused
175         files laying around. Strictly speaking, after having built
176         and installed Zope once, there is no need to keep the
177         building directory and you might remove it afterwards.
178
179       * *pkgs/ -- Repository for packages downloaded*
180
181         Also this directory is not neccessary, to build
182         Zope. It is a place to store packages, downloaded from the
183         internet, especially Zope products or Zope
184         source-tarballs. It comes in handy, if you want to keep
185         packages for later use. We will use it to keep a backup of
186         the Zope sources and CPS products, so we do not have to
187         download them from internet everytime we create a new
188         instance.
189
190       * *instances/ -- The Zope instances directory*
191
192         The most important directory in daily use. Here we create our
193         Zope instances and here we will spend the most time, once,
194         one or more insances are created and run.
195
196     As you might already guessed, there is no need to create such a
197     directory structure. Furthermore you can give the directories
198     other names, whatever you like. In daily work it turned out, that
199     such a directory tree is very handy and it tends to be a kind of
200     best practice, to use it.
201
202     On the commandline the directory tree is created like so:
203
204       ::
205
206         ~$ mkdir zope
207         ~$ mkdir zope/base zope/build zope/pkgs zope/instances
208
209  3. *Unpack the sources*
210
211     The sources are packed in a so-called 'tarball', which is denoted
212     by the file extension 'tgz', a short form of 'tar.gz'.
213
214     Now, as we freshly created a directory for building, we first copy
215     the downloaded tarball containing the Zope sources to the build
216     directory:
217
218       ::
219
[3860]220         ~$ cp Zope-2.9.8-final.tgz zope/build
[1617]221
222     Afterwards we put the sources into the pkgs-directory to keep it
223     for later use (and remove it from our home directory):
224
225       ::
226
[3860]227         ~$ mv Zope-2.9.8-final.tgz zope/pkgs
[1617]228
229     The command 'mv' *moves* a file to a different location, thereby
230     deleting the old file.
231
232     Now we can change to the build-directory and unpack the sources:
233
234       ::
235
236         ~$ cd zope/build
[3860]237         ~/zope/build$ tar -xzf Zope-2.9.8-final.tgz
[1617]238
239     The commandline options 'xzf' mean: e(x)tract the file, un(z)ip the
[3860]240     file and do the whole operation on the (f)ile Zope-2.9.8-final.tgz.
[1617]241
[3860]242     This creates a new subdirectory 'Zope-2.9.8-final' with all required
[1617]243     sources.
244
245  4. *Build Zope base*
246
247     Change to the sources directory:
248
249       ::
250
[3860]251         ~/zope/build$ cd Zope-2.9.8-final
[1617]252
253     Here you can find a file configure, which is most important, to
254     get all compile time options, supported by your Zope version. You
255     can view them by calling './configure --help':
256
257       ::
258
[3860]259         ~/zope/build/Zope-2.9.8-final$ ./configure --help
[1617]260
261         configure [--help] [--quiet] [--with-python=path] [--prefix=path]
262
263         Create a Makefile suitable for building Zope
264
265         Options:
266          --help              shows usage and quits
267          --quiet             suppress nonessential output
268          --with-python       specify a path to a Python interpreter to use
269          --prefix            specify an installation path for binary data
270
271         Given no options, configure will search your PATH for a suitable
[3860]272         Python interpreter and use '/usr/local/Zope-2.9.8-final' as a prefix.
[1617]273
274     Basically, it tells you, that you can give a special Python
275     version to build Zope and an installation path. Usually, it is
276     best to let the configure script look for an appropriate Python
277     interpreter.
278
279     Note, that for building Zope you not only have to provide a
280     running Python interpreter (preferably version 2.4.3), but also
281     the header files and related developer files of your Python
282     installation. Usually on Linux those packages are called
283     python-dev or similar. The exact package name depends on your
284     distribution.
285
286     On Debian/Ubuntu based systems you can install the package
287     'python2.4-dev', which has to be done as superuser (denoted by
288     the '#'-sign in the follwing):
289
290       ::
291
292         ~# apt-get install python2.4-dev
293
294     While the Python developer files are rarely installed on usual
295     end-user systems (except Zope users), the most systems already
296     have a C-compiler (most common on Linx: gcc) installed, which you
297     need too to build Zope. If Zope complains while building about
298     unknown files or similar, make sure you have intalled the 'gcc'
299     and the Python developer files. Consult your distributions'
300     documentation to learn, how to do this.
301
302     To start the real built, we give the 'configure'-script a
303     prefix-option, which tells, that we want to have installed Zope
304     in the base/ directory:
305
306       ::
307
[3860]308         ~/zope/build/Zope-2.9.8-final$ ./configure --prefix=/home/user/zope/base/2_9_8
[1617]309
310     Here we want Zope to be installed in
[3860]311     /home/user/zope/base/2_9_8. Note, that the path
[1617]312     /home/user/zope/base/ must already exist before executing the
[3860]313     above command, while the subdirectory '2_9_8' (yes, its a
[1617]314     diretory name) should be created by the build process.
315
316     You can however use any name you want for your Zope installation,
317     for example 'zope293' or something similar. Just change the
318     prefix-parameter in that case accordingly.
319
320     If everthing went well, you got the following (or similar) output:
321
322       ::
323
324         Configuring Zope installation
325         
326         Testing for an acceptable Python interpreter...
327         
328         Python version 2.4.3 found at /usr/bin/python
329         
330         The optimum Python version (2.4.3) was found at /usr/bin/python.
331
332     In case of errors, you might provide a --with-python option.
333
334     The Zope package is now configured and ready to be built. We
335     start the process by doing:
336
337       ::
338 
[3860]339         ~/zope/build/Zope-2.9.8-final$ make
[1617]340
341     and, if everything worked fine:
342
343       ::
344
[3860]345         ~/zope/build/Zope-2.9.8-final$ make install
[1617]346
347     The first step, the call of 'make', takes the biggest amount of
348     time and is the crucial part of the whole installation process.
349
350     The make command may raise some compiler warnings (complaining
351     about eventually uninitialized variables), especially, if using
352     the up-to-date version of gcc. You can safely ignore them.
353
354     But if you get real error messages (not only warnings) something is
355     seriously wrong and you have to resolve this problems before
356     proceeding. In most cases it is a matter of (not) installed Python/gcc
357     packages and depends on your system. There is a very high
358     probability, that you can find some hints regarding your issues
359     using Google or other internet ressources.
360
361     If no serious errors occured: congratulations! You finally
362     installed your first Zope.
363
364     If you are short of disk space, you can now safely remove the
365     complete directory tree in the 'build/' directory. All needed
366     software is now installed in the base/ directory.
367
368
369  5. *Install a Zope instance*
370
371     We can now change to our freshly created Zope installation:
372
373       ::
374
[3860]375         ~$ cd /home/user/zope/base/2_9_8
[1617]376
[3860]377     Instead of '2_9_8' you must use the name given to the prefix
[1617]378     option of the 'configure'-script above.
379
380     Here you can find some subdirectories of which for now only the
381     bin-directory is of interest:
382
383       ::
384
[3860]385         ~/zope/base/2_9_8$ ls
[1617]386         bin  include  lib  skel  zopeskel
[3860]387         ~/zope/base/2_9_8$ cd bin
388         ~/zope/base/2_9_8/bin$ ls
[1617]389         analyze.py        fstail.py           requestprofiler.py   zeoctl.py
390         checkbtrees.py    fstest.py           runzeo.py            zeopack.py
391         check_catalog.py  load_site.py        simul.py             zeopasswd.py
392         compilezpy.py     migrate.py          space.py             zeoqueue.py
393         copyzopeskel.py   mkzeoinstance.py    stats.py             zeoreplay.py
394         copyzopeskel.pyc  mkzeoinst.py        test.py              zeoserverlog.py
395         decompilezpy.py   mkzopeinstance.py   timeout.py           zeoup.py
396         fsdump.py         netspace.py         zconfig              zodbload.py
397         fsoids.py         parsezeolog.py      zconfig_schema2html  zopetest
398         fsrefs.py         reindex_catalog.py  zdctl.py             zpasswd.py
399         fsstats.py        repozo.py           zdrun.py
400
401    Almost all of these files are executables, i.e. programs, you
402    might need in your further work with Zope. Most Zope
403    administrators, however, know only the script 'mkzopeinstance.py',
404    which creates a new Zope instance. We will use it too. First we
405    call it with the '--help' option, to see, what the script can do
406    for us:
407
408      ::
409
[3860]410        ~/zope/base/2_9_8/bin$ ./mkzopeinstance.py --help
[1617]411        mkzopeinstance.py:  Create a Zope instance home.
412
413        usage:  mkzopeinstance.py [options]
414
415        Options:
416         -h/--help -- print this help text
417         -d/--dir  -- the dir in which the instance home should be created
418         -u/--user NAME:PASSWORD -- set the user name and password of the initial user
419         -s/--skelsrc -- the dir from which skeleton files should be copied
420
421        When run without arguments, this script will ask for the information necessary
422        to create a Zope instance home.
423
424    Note: On UN*X systems the '--help' switch is very common. Most programs
425    support it.
426
427    The help message displayed tells us, that we can name a directory
428    to specify, where the instance should be created and a
429    username/password pair for the initial login. That is, what we are
430    going to do. As path for the instance we choose a (yet not
431    existing) directory in the 'instances'-directory, say
432    'myinstance1'. The user/password values for our first local tries
433    can be kept simple:
434
435      ::
436
[3860]437        ~/zope/base/2_9_8/bin$ ./mkzopeinstance.py -d /home/user/zope/instances/myinstance1 -u user:secret
[1617]438
439    This takes only about one second. If you do not give a username
440    and password via parameters, you will be prompted for the data.
441
442  6. *Configure and start your new instance*
443
444    Change to the instances directory, to see, whether your new Zope
445    instance was created:
446
447      ::
448
449        ~$ cd /home/user/zope/instances
450        ~/zope/instances$ ls
451        myinstance1
452
453    Okay, the instance exists, so go in and have a look:
454
455      ::
456
457        ~/zope/instances$ cd myinstance1
458        ~/zope/instances/myinstance1$ ls
459        bin  etc  Extensions  import  inituser  lib  log  Products  README.txt  var
460
461    Here we see the main directories for the further work with
462    Zope. The most important directories:
463
464      * *bin -- Executables to start/stop your instance*
465
466        This directory contains the programs to start or stop your
467        Zope instance. You can do much more with them, but we refer to
468        the extended possibilities later on.
469
470      * *etc -- Configuration of your instance*
471
472        This directory holds the important configuration file of your
473        Zope instance. Chances are, that you do not need to change the
474        default configuration, but we will take a look into it anyway.
475
476      * *log -- Logfiles of your instance*
477
478        Here you can find the logs of your instance. Namely the access
479        logfile 'Z2.log' and an error log called 'event.log'. The
480        event log saves all Zope specific events, not only errors.
481
482      * *Products -- 3rd-party products repository*
483
484        Here can install all products, like CPS or the WAeUP SRP
485        product. They are generally installed on a per-instance basis.
486
487      * *var -- The data directory*
488
489        In this directory will Zope save all runtime information,
490        i.e. the Z Object DataBase (ZODB) and other temporary
491        data. The ZODB will be held in a file called Data.fs, which
492        contains all the data you entered into the running Zope
493        system. If it gets corrupted, the whole instance is lost. In
494        special cases (ZEO setup etc.) the Data.fs can be shared
495        amongst several Zope instances and reside at another place.
496
497    Before starting the instance, first have a look at the
498    configuration file 'zope.conf' which can be found in the
499    etc-directory of your instance.
500
501    With growing version numbers of Zope also the Zope configuration
[3860]502    file grows larger and larger. For version 2.9.8 there are too many
[1617]503    options available in zope.conf, to discuss every single option
504    herein.
505
506    One option, however, is of special interest: the port number,
507    where the Zope instance will listen to requests.
508
509    'zope.conf' is a simple plain text file, which you can edit with
510    any text editor (please do not use something like OpenOffice or
511    Word to edit a plain text file: it won't be plain text any
512    more). To view its content you can use the command 'less' on
513    UN*X.
514
515    In the zope.conf you will find (near the end of file) a section
516    called 'http-server', which looks like this:
517
518      ::
519
520        #
521        #     An HTTP server starts on port 8080.
522
523        <http-server>
524        # valid keys are "address" and "force-connection-close"
525          address 8080
526          # force-connection-close on
527        </http-server>
528
529    This means, Zope will listen on port 8080. This is okay, if there
530    is no other process still listening on port 8080 (note for geeks:
531    you can use the 'netstat' tool to check, which ports are already
532    in use). But if you want to run several Zope instances in
533    parallel, you must set the listening port to another value.
534
535    We assume, port 8080 is not in use and simply start the Zope
536    instance in the foreground for the first time:
537
538      ::
539
540        ~/zope/instances/myinstance1$ ./bin/runzope
541
542    You will get some DeprecationWarnings and a message about a
543    installed sighandler. This means, Zope has started and you should
544    be able to use your Browser and browse to
545
546      http://localhost:8080/
547
548    Note the portnumber in the URL:
549
550      .. image:: ./snapshot1.png
551
552    If you can see the Zope Quick Start screen, everything is fine and
553    you can stop the Zope instance on the console by typing CTRL-C.
554
555    We used the 'runzope' script to start Zope in the foreground. This
556    is a recommended way to start freshly created instances, because
557    problems occurring during the startup process will be displayed
558    directly on the screen (in the shell).
559
560    For long-term use this is not an option, because you want to run
561    Zope as a server, which runs in the background and continues to
562    run, when you log out. To start Zope in background use the
563    'zopectl' command. It requires a parameter, which specifies the
564    action to be taken:
565
566      ::
567
568        zopectl start|stop|restart
569
570    There are other possible actions as well, but for the beginning we
571    start with 'start':
572
573      ::
574
575        ~/zope/instances/myinstance1$ ./bin/zopectl start
576        . . . daemon process started, pid=457
577
578    You now have Zope running in regular mode. Check it by visiting
579    the Quick Start Page.
580
581    If everything went fine, you can see the startup messages in the
582    logfiles in the log directory of your instance.
583
584    You can also enter the Zope Management Interface (ZMI), by adding
585    '/manage' to the URL:
586
587      http://localhost:8080/manage
588
589    This requires to enter the credentials, you gave during
590    installation of the instance.
591
592      .. image:: ./snapshot2.png
593
594    After successfull authorization you should be able to see the ZMI:
595
596      .. image:: ./snapshot3.png
597
598That's it. You installed Zope successfully. Congratulations! To
599stop your running instance, you can go to the control panel in the
600ZMI and shutdown by mouse-click, or, on the commandline, do
601
602  ::
603
604    ~/zope/instances/myinstance1$ ./bin/zopectl stop
605
606You can play a bit with your instance and then try to do the other
607steps to run a fully working version of the WAeUP SRP.
608
609*Have fun!*
610
611*Uli Fouquet*
[3860]612
613(updated in 2009-01 to Zope 2.9.8, as used by current WAeUP portals, by Hraban)
Note: See TracBrowser for help on using the repository browser.