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

Last change on this file since 1823 was 1617, checked in by uli, 18 years ago

Added extended instructions for installing Zope (part 1).

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