source: main/waeup.kofa/trunk/docs/INSTALL.txt @ 13599

Last change on this file since 13599 was 13270, checked in by uli, 9 years ago

Fix typo.

File size: 13.8 KB
RevLine 
[11381]1Installation of Kofa
2####################
[10120]3
[12967]4These are generic installation instructions for the WAeUP_ Kofa
[11381]5student information portal and customized versions thereof.
[10120]6
[11381]7For specific aspects of this package please refer to the local README
8file.
[10120]9
[11381]10Please note, that **only Linux-based installs** are described and actively
11supported. We recommend use of Debian_ / Ubuntu_.
[11323]12
[11381]13.. note:: This means we do not actively support Windows(tm)!
[11323]14
[12864]15.. contents:: Table of Contents
16   :local:
[11323]17
[12968]18.. _prerequisites:
[11384]19
[11381]20Prerequisites
21*************
[11323]22
[11381]23The Kofa packages are based on `Grok`_, which is a Python_
[13075]24framework for agile web application development. Grok_ itself is based
[11381]25on `Zope`_.
[11323]26
[11381]27Both, Grok_ and Zope_, are written in the `Python`_ programming
28language (with parts written in C). You therefore have to have
29`Python`_ installed (including `Python`_ headers).
[11323]30
31
[11381]32Preparing the System
[11323]33====================
34
[12967]35For a Kofa install we need of course `Python`_ installed as well as
[11381]36some standard developer tools like C compilers, C libraries, etc.
[11323]37
38What you need (Debian/Ubuntu package names in brackets):
39
[11381]40* Python 2.7 (``python2.7``)
[11323]41
[11381]42* Python 2.7 development files (``python2.7-dev``)
[11323]43
[11381]44* A C-Compiler with basic C developer libraries (``build-essential``)
[11323]45
[11527]46* A subversion client (``subversion``)
[11323]47
[11527]48* XML and XSLT development libraries (``libxml2-dev``, ``libxslt1-dev``)
49
[11381]50* enscript (``enscript``) [optional]
[11323]51
52  This is only needed if you want test coverage reports.
53
54All these packages can be installed on Debian systems like this::
55
[11527]56  $ sudo apt-get install python2.7 python2.7-dev subversion \
57                         build-essential enscript libxml2-dev libxslt1-dev
[11323]58
59Afterwards you should be able to enter::
60
61  $ python2.7
62
[11381]63at the commandline and get a Python_ prompt. Quit the interpreter
[11323]64pressing <CTRL-D>.
65
66
67Installing `virtualenv`
68=======================
69
[11382]70We strongly suggest use of `virtualenv`_ to create Python_ sandboxes
71where you can run your code without touching any other installations.
[11323]72
[12967]73`virtualenv`_ is also the only possibility to build a Kofa install
[11382]74without the need of superuser permissions. In short: `virtualenv`_
75will make your life easier. Use it.
[11323]76
[11382]77Detailed install instructions for `virtualenv`_ can be found on
78http://www.virtualenv.org/en/latest/virtualenv.html#installation.
[11323]79
[11382]80The short way for a user install (no superuser perms required) is like
81this::
[11323]82
[11382]83  $ curl -O https://pypi.python.org/packages/source/v/virtualenv/virtualenv-1.11.4.tar.gz#md5=9accc2d3f0ec1da479ce2c3d1fdff06e
84  $ tar xvfz virtualenv-1.11.4.tar.gz
85  $ cd virtualenv-1.11.4
86  $ python virtualenv.py py27
[11323]87
[11382]88Superusers can install `virtualenv`_ system-wide much easier. On
89`Debian`_/`Ubuntu`_ systems where you have superuser permissions, you
90can install `virtualenv`_ via::
[11323]91
[11382]92  $ sudo apt-get install python-virtualenv
[11323]93
[11401]94*Or*, if `pip` is installed already (superusers can install it via
95 ``sudo apt-get install python-pip`` on `Debian`_/`Ubuntu`_)::
[11323]96
[11382]97  $ sudo pip install virtualenv
[11323]98
99
[11402]100Creating a Sandbox
[11323]101==================
102
[11383]103After installing `virtualenv`_ you can install local sandboxes like
[11401]104this (if `virtualenv` is installed system-wide)::
[11323]105
[11383]106  $ virtualenv --no-site-packages py27
[11323]107
[11401]108*or* like this::
109
110  $ python /path/to/my/virtualenv.py --no-site-packages py27
111
[11383]112where ``py27`` is a directory in the filesystem where your sandbox
113will be created. `virtualenv` will also create this directory for
[11401]114you. While you can pick any sandbox name you want, it is recommended
115to use a sandbox name that is short and at the same time reflects the
116Python version used (here: Python 2.7).
[11323]117
118By passing the ``no-site-packages`` switch we tell `virtualenv` to
[11401]119provide a clean environment without any extra-packages installed
[11383]120systemwide. More recent versions of `virtualenv`_ have this option set
121by default.
[11323]122
[11383]123Another often used option of `virtualenv`_ is ``-p``. With ``-p`` you
124can tell `virtualenv`_ which Python executable to use as base for the
125new sandbox.
126
[11323]127You now can activate the sandbox by doing::
128
[11383]129  $ source py27/bin/activate
130  (py27)$
[11323]131
[11401]132You will notice that the input prompt changes, indicating the name of
133the sandbox activated.
[11323]134
135To deactivate the sandbox at any time, enter::
136
[11383]137  (py27)$ deactivate
[11323]138
139and the prompt will be the same as before the activation.
140
141For the following steps make sure the sandbox is active.
142
143
[11402]144Getting the Sources
145===================
[11323]146
[11401]147Now, as the sandbox is activated (see above, if not), we can fetch the
148sources for Kofa.
[11323]149
[11401]150As Kofa is currently available from the Subversion_ repository only,
151we use the Subversion_ client `svn` and checkout the main devel branch
152of the `waeup.kofa` package like this::
[11323]153
[11401]154  (py27)$ svn co https://svn.waeup.org/repos/main/waeup.kofa/trunk
[11323]155
156The command should fetch the Kofa base package sources for you and
[11401]157will put everything in a new directory ``trunk/``.
[11323]158
159Now enter the new directory::
160
[11401]161  (py27)$ cd trunk/
[11323]162
[11401]163and you can start building the real package.
[11323]164
[11401]165.. note:: If you not want to work with the `waeup.kofa` package but a
166          customized package (like ``waeup.aaue`` or similar), then
167          you can use the above checkout command but with
168          ``waeup.kofa`` replaced by the name of the customized
169          package::
[11381]170
[11401]171            (py27)$ svn co https://svn.waeup.org/repos/main/<PKG-NAME>/trunk
[11381]172
[11401]173          For the exact link, please refer to the README.txt file in
174          your package.
175
176
[11402]177Bootstrapping the Build
178=======================
179
180After `Creating a Sandbox`_ and `Getting the Sources`_ we have to
181initialize the newly created development environment::
182
183  (py27)$ python bootstrap.py
184
185This should create a local ``bin/`` directory with at least a script
186``buildout`` in it.
187
188If bootstrapping fails, chances are, that you need the `distribute`
189package installed. In a virtual environment you can install it without
[11703]190interfering with other packages installed on your server::
[11402]191
192  (py27)$ pip install --upgrade distribute
193
194Afterwards you have to retry the bootstrapping, until you get a
195working ``buildout`` script in the local ``bin/`` directory.
196
197Once the ``buildout`` script exists, you do not have to activate the
198virtual envronment any more (although you can).
199
200
[11381]201Part 1: Single Client Setup
202***************************
203
[12967]204You can run Kofa with a single client (useful for evaluation,
[11401]205development, etc.) or with multiple clients running in parallel. The
206latter setup is useful in productive environments with many thousands
[11402]207users and called a ``ZEO`` install. We will cover both setup
208types. The first is covered here, the latter one is covered in `Part
2092: ZEO Install`_.
[11401]210
[11402]211
[11404]212Building the Package
213====================
[11323]214
[11404]215In the sources directory (``trunk/``) you have to prepare the
[11323]216project to fetch needed components (eggs), compile C-code parts,
[11404]217etc. This is done by a single command ``buildout``::
[11323]218
[11404]219  $ ./bin/buildout
[11323]220
221If this is your first install of some Grok-related project, this step
222will need some time as lots of sources have to be fetched, many
223components must be compiled, etc.
224
225This step must be redone whenever you change something in
[11404]226``buildout.cfg``, ``buildout-zeo.cfg``, or ``setup.py``.
[11323]227
228Note that if you have more than one sandbox for a Zope-based web
229application, it will probably make sense to share the eggs between the
230different sandboxes.  You can tell ``zc.buildout`` to use a central
231eggs directory by creating ``~/.buildout/default.cfg`` with the
232following contents::
233
[11385]234  [buildout]
235  eggs-directory = /home/bruno/buildout-eggs
[11323]236
[11404]237where the given directory should be exist beforehand. All eggs of all
238`buildout` projects will then be stored in this directory (and not
239fetched anew if already existing there).
[11323]240
[11404]241
242Start the Instance
[11323]243==================
244
245You should be able now to start the created instance by doing::
246
[11404]247  $ ./bin/kofactl fg
[11323]248
[11385]249Alternatively you can do::
[11323]250
[11404]251  $ bin/paster serve parts/etc/deploy-themed.ini
[11323]252
253The port numbers where Kofa is running on your server are defined in
[11404]254`buildout.cfg` under ``[kofa_params]``.
[11323]255
[11404]256If you now point a browser to the right port on your server, for example::
[11323]257
[11385]258  localhost:8080
[11323]259
260you should get a login pop-up, where you can login as superuser with
261``grok`` and ``grok`` as username/password (Kofa base package only!).
262
263You can stop the instance by pressing <CTRL-C>.
264
265If you are connected and logged in,
266you should be able to add the grok-based applications
267(such as ``University``) from the menu.
268
269Add an instance of ``University`` and click on the link next to the
270then visible entry in the list of installed applications.
271
[11404]272Running the Tests
[11323]273=================
274
[11404]275All WAeUP_ packages come with comprehensive test suites ensuring the
276software quality also after changes and updates.
[11323]277
[11404]278The package tests are easily run by executing the test runner
279from the ``bin`` directory::
[11323]280
[11404]281  $ ./bin/test
[11323]282
[11404]283Use the ``-c`` option to get coloured output. Use the ``--pdb`` option
284to start the Python_ debugger when a test fails.
285
286
[11402]287Part 2: ZEO Install
288*******************
[11323]289
290Each ZEO install consists of at least one ZEO server and normally two
291or more ZEO clients. While the ZEO server is meant to manage the ZODB
292database for clients, the clients connect to the outside world, listen
293for request and do the real dataprocessing.
294
295We prepared a `buildout` configuration that sets up one server
296configuration and two client configs. This configuration is in
297``buildout-zeo.cfg``.
298
[11405]299Generating the ZEO Setup
[11323]300========================
301
302To install Kofa ZEO-based you can run `buildout` with the given
303(or your own) configuration file like this::
304
305  $ ./bin/buildout -c buildout-zeo.cfg
306
307This should generate all scripts necessary to run servers, clients,
308etc.
309
[11405]310Starting ZEO Servers and Clients
[11323]311================================
312
313First start the server::
314
315  $ ./bin/zeo_server start
316
317Clients can be started by doing::
318
319  $ ./bin/zeo_client1 start
320  $ ./bin/zeo_client2 start
321
322This will start both clients in daemon mode.
323
324Instead of ``start`` you can, as usually, start an instance in
325foreground (``fg``), etc. You know the drill.
326
327
[11405]328Manually Starting ZEO Clients
[11323]329=============================
330
331This is normally not neccessary.
332
333``zeo_clientN`` scripts are basically wrappers around calls to
334``bin/paster``. You can bypass this wrapper and start a client
335'manually' like this::
336
337  $ ./bin/paster serve --pid-file var/zeo1.pid --daemon \
338        pars/etc/zeo1.ini
339
[11405]340It is important to give a pid-file as `paster` otherwise can not start
[11323]341different clients (they would all refer to the same pid file
342`paster.pid` and refuse to start after the first client was started).
343
344
[13270]345Setup (parameters, ports, etc.)
346===============================
[11323]347
348By default the server will listen on port 8100 for requests from
349localhost (not: from the outside world).
350
351You can change ZEO server settings in the ``[zeo_server]`` section
352of ``buildout-zeo.conf``. Run `buildout` afterwards.
353
354The clients will listen on port 8081 and 8082. You can change settings
355in ``etc/zeo1.ini.in`` and ``etc/zeo2.ini.in`` respectively. Run
356buildout after any change.
357
358If you want to change the paster wrapper for any zeo client, you can
359edit ``etc/zeo1.conf`` and/or ``etc/zeo2.conf``. Run buildout
360afterwards.
361
362
[11405]363Stopping ZEO Servers and Clients
364================================
[11323]365
[11405]366Given everything was started in daemon mode, first stop the clients::
[11323]367
[11405]368  $ ./bin/zeo_client1 stop
369  $ ./bin/zeo_client2 stop
[11323]370
[11405]371Then stop the ZEO server::
372
373  $ ./bin/zeo_server stop
374
375
376Creating New ZEO Clients
377========================
378
379You want more ZEO clients to be created by `buildout`? Easy. Three
380steps are neccessary.
381
3821. Create config files in `etc/`
383--------------------------------
384
[11323]385Each client needs two configuration files:
386
387  - ``etc/zeoN.conf``
388       configuring the paster wrapper
389
390  - ``etc/zeoN.ini``
391       configuring the runtime config, ports, etc.
392
393Just copy over these files from the already existing zeo1/zeo2 files
394and replace ``zeo1`` or ``zeo2`` with your new name.
395
3962. Update buildout-zeo.cfg
397--------------------------
398
399Here, inside ``buildourt-zeo.cfg`` also three steps are needed.
400
401* 2.1. Create new .ini and .conf entries
402
403  The .conf and .ini files in etc/ are only templates that have to be
404  generated in their really used final location. In buildout-zeo.cfg
405  you can care for this by creating a new ``[zeoN_ini]`` and
406  ``[zeoN_conf]`` option (replacing ``N`` with a number, of course).
407
408  Just copy over existing entries and replace the mentions of ``zeo1``
409  or ``zeo2`` by your ``zeoN``.
410
411* 2.2. Create a new ``zeo_clientN`` entry
412
413  Then you have to create an entry that will generate the
414  ``zeo_clientN`` script. Again, just copy over an existing
415  ``[zeo_client1]`` entry and replace ``1`` withg your client number.
416
417* 2.3. Register the new sections in ``[buildout]`` section
418
419  When done with the above: add the new section in ``[buildout]``::
420
421    [buildout]
422      ...
423      <old entries...>
424      ...
425      zope_conf_zeo_5
426      zeo5_ini
427      zeo_client5
428
429  depending on how you named your new sections.
430
4313. Rerun ``buildout``
432---------------------
433
434When adding or removing client/server instances, make sure to stop all
435running servers/clients before rerunning buildout.
436
437To activate the new setup, rerun buildout::
438
439  $ bin/buildout -c buildout-zeo.cfg
440
441This should generate any new clients and remove older ones or just
442update configuration files.
443
444
445Considerations
446==============
447
448There are some things in the current buildout-zeo.cfg we might do not
449want. It extends the regular ``buildout.cfg`` so that we do not have
450to repeat most sections but the ``parts`` in ``[buildout]`` have to be
451listed.
452
453We need, however, not everything with a ZEO-deploy that is listed in a
454default buildout. We might do not need docs, no profiling, etc. Also a
455regular non-ZEO kofactl might not make to much sense. Therefore all
456this might be subject to changes.
[11381]457
458.. _Debian: http://www.debian.org/
459.. _Grok: http://grok.zope.org/
460.. _Python: http://www.python.org/
[11401]461.. _Subversion: http://subversion.apache.org/
[11381]462.. _Ubuntu: http://www.ubuntu.com/
463.. _virtualenv: http://www.virtualenv.org/en/latest/
464.. _WAeUP: https://www.waeup.org/
465.. _Zope: http://www.zope.org/
466.. _zc.buildout: http://cheeseshop.python.org/pypi/zc.buildout
Note: See TracBrowser for help on using the repository browser.