Changeset 11323 for main


Ignore:
Timestamp:
23 Feb 2014, 07:17:35 (11 years ago)
Author:
Henrik Bettermann
Message:

Merge the various readmes and installation guides to one single readme txt file.

Update the installation instructions.

Location:
main/waeup.aaua/trunk
Files:
1 added
2 deleted
1 edited

Legend:

Unmodified
Added
Removed
  • main/waeup.aaua/trunk/README.txt

    r10120 r11323  
    1 What is `waeup.kofa`?
    2 *********************
    3 
    4 The WAeUP Student Information and Registration Portal. `waeup.kofa` is
    5 a web-based management tool for managing universities and schools.
    6 
    7 The package was created as an effort of the WAeUP group. See
    8 http://www.waeup.org to learn more about WAeUP.
    9 
    10 Installation instructions can be found in the User Documentation (docs folder in the file system).
     1Installation of Kofa on Linux production system
     2###############################################
     3
     4.. note:: `waeup.kofa` and its custom packages
     5          might not work with Python > 2.7
     6          currently. Use of Python 2.7 is recommended.
     7          The installation is described for Linux-based computers.
     8
     9Part 1: Deploying Kofa as a single Zope client install
     10******************************************************
     11
     12Prerequisites
     13=============
     14
     15The Kofa packages are based on `Grok`_, which is a Python
     16framework for agile webapplication development. Grok itself is based
     17on `Zope`_.
     18
     19.. _Grok: http://grok.zope.org/
     20
     21.. _Zope: http://www.zope.org/
     22
     23Both, Grok and Zope, are written in Python (with parts written in
     24C). You therefore need `Python`_ installed.
     25
     26.. _Python: http://www.python.org/
     27
     28Note, that you also need the Python header files and a compiler to
     29compile the parts written in C.
     30
     31To deploy Kofa most easily, we use `zc.buildout`_
     32
     33.. _zc.buildout: http://cheeseshop.python.org/pypi/zc.buildout
     34
     35
     36Preparing the system
     37====================
     38
     39To create a working copy of Kofa we recommend use of
     40`virtualenv`. You, however, need also some basic libraries, a C
     41compiler and some things more.
     42
     43What you need (Debian/Ubuntu package names in brackets):
     44
     45* Python 2.7 (python2.7)
     46
     47* Python 2.7 development files (python2.7-dev)
     48
     49* A C-Compiler (gcc)
     50
     51* The C library development files (libc6-dev)
     52
     53* A subversion client (svn)
     54
     55* enscript (enscript) [optional]
     56
     57  This is only needed if you want test coverage reports.
     58
     59All these packages can be installed on Debian systems like this::
     60
     61  # apt-get install python2.7 python2.7-dev python2.7-dbg \
     62                    gcc libc6-dev svn enscript
     63
     64Afterwards you should be able to enter::
     65
     66  $ python2.7
     67
     68at the commandline and get a Python prompt. Quit the interpreter
     69pressing <CTRL-D>.
     70
     71
     72Installing `virtualenv`
     73=======================
     74
     75We recommend use of `virtualenv` to create Python sandboxes where you
     76can run your code without touching any other installations.
     77
     78If you don't already have ``easy_install`` available, you can find the
     79script to set it up on the `PEAK EasyInstall page`_.
     80
     81.. _`PEAK EasyInstall page`: http://peak.telecommunity.com/DevCenter/EasyInstall#installing-easy-install
     82
     83You need to download `ez_setup.py`_. Then, you run it like this to
     84install ``easy_install`` into your system Python::
     85
     86  $ sudo python2.7 ez_setup.py
     87
     88.. _`ez_setup.py`: http://peak.telecommunity.com/dist/ez_setup.py
     89
     90This will make ``easy_install`` available to you.
     91
     92.. note:: Sometimes you have ``easy_install`` installed but you need a
     93          newer version of the underlying setuptools infrastructure to
     94          make Grok work. You can upgrade setuptools with::
     95
     96            $ sudo easy_install -U setuptools
     97
     98Now you can install `virtualenv` by doing (as root)::
     99
     100  # easy_install-2.7 virtualenv
     101
     102This step will fetch all needed sources from the internet and install
     103`virtualenv` locally in your Python2.7 installation.
     104
     105
     106Creating a sandbox
     107==================
     108
     109This step is only necessary (and recommended) if you installed
     110`virtualenv` before.
     111
     112As a normal user you now can create a sandbox for your upcoming work
     113by::
     114
     115  $ virtualenv --no-site-packages mysandbox
     116
     117where ``mysandbox`` is a directory in the filesystem where your
     118sandbox will be created. `virtualenv` will also create this directory
     119for you.
     120
     121By passing the ``no-site-packages`` switch we tell `virtualenv` to
     122provide us a clean environment without any extra-packages installed
     123systemwide.
     124
     125You now can activate the sandbox by doing::
     126
     127  $ source mysandbox/bin/activate
     128
     129You will notice that the input prompt changes.
     130
     131To deactivate the sandbox at any time, enter::
     132
     133  (sandbox27)$ deactivate
     134
     135and the prompt will be the same as before the activation.
     136
     137For the following steps make sure the sandbox is active.
     138
     139
     140Creating a working place
     141========================
     142
     143In the sandbox we now create our real working
     144environment. To do this, we change to the sandbox and checkout the
     145sources of Kofa from the subversion server::
     146
     147  (sandbox27)$ cd mysandbox/
     148  (sandbox27)$ svn co https://svn.waeup.org/repos/main/waeup.kofa/trunk kofa-trunk
     149
     150where ``kofa-trunk`` is only a name we've chosen here to make clear
     151where the sources come from. In this case we are installing the Kofa base
     152package.
     153
     154The command should fetch the Kofa base package sources for you and
     155put it in the directory ``kofa-trunk/``.
     156
     157Now enter the new directory::
     158
     159  (sandbox27)$ cd kofa-trunk
     160
     161
     162Preparing the build
     163===================
     164
     165In the sources directory (``kofa-trunk/``) you have to prepare the
     166project to fetch needed components (eggs), compile C-code parts,
     167etc. This steip will not touch any external projects::
     168
     169  (sandbox27)$ python bootstrap.py
     170
     171This will generate some directories and the ``buildout`` script in
     172``bin/`` for us. This step must be executed only once for each
     173instance.
     174
     175You can now deactivate the sandbox::
     176
     177  (sandbox27)$ deactivate
     178
     179Now we can do the real build by triggering::
     180
     181  $ bin/buildout
     182
     183If this is your first install of some Grok-related project, this step
     184will need some time as lots of sources have to be fetched, many
     185components must be compiled, etc.
     186
     187This step must be redone whenever you change something in
     188``buildout.cfg`` or ``setup.py``.
     189
     190Note that if you have more than one sandbox for a Zope-based web
     191application, it will probably make sense to share the eggs between the
     192different sandboxes.  You can tell ``zc.buildout`` to use a central
     193eggs directory by creating ``~/.buildout/default.cfg`` with the
     194following contents::
     195
     196    [buildout]
     197    eggs-directory = /home/bruno/buildout-eggs
     198
     199
     200Start the instance
     201==================
     202
     203You should be able now to start the created instance by doing::
     204
     205   $ bin/zopectl fg
     206
     207Alternatively you can do:
     208
     209    $ bin/paster serve parts/etc/deploy.ini
     210
     211The port numbers where Kofa is running on your server are defined in
     212buildout.cfg under [kofa_params].
     213
     214If you now point a browser to the right port on your server, for example ::
     215
     216   localhost:8080
     217
     218you should get a login pop-up, where you can login as superuser with
     219``grok`` and ``grok`` as username/password (Kofa base package only!).
     220
     221You can stop the instance by pressing <CTRL-C>.
     222
     223If you are connected and logged in,
     224you should be able to add the grok-based applications
     225(such as ``University``) from the menu.
     226
     227Add an instance of ``University`` and click on the link next to the
     228then visible entry in the list of installed applications.
     229
     230Running the tests
     231=================
     232
     233The tests are easily run by executing the test runner that's
     234installed in the ``bin`` directory::
     235
     236    $ bin/test
     237
     238
     239Part 2: Deploying Kofa as ZEO install
     240*************************************
     241
     242Each ZEO install consists of at least one ZEO server and normally two
     243or more ZEO clients. While the ZEO server is meant to manage the ZODB
     244database for clients, the clients connect to the outside world, listen
     245for request and do the real dataprocessing.
     246
     247We prepared a `buildout` configuration that sets up one server
     248configuration and two client configs. This configuration is in
     249``buildout-zeo.cfg``.
     250
     251Generating the ZEO setup
     252========================
     253
     254To install Kofa ZEO-based you can run `buildout` with the given
     255(or your own) configuration file like this::
     256
     257  $ ./bin/buildout -c buildout-zeo.cfg
     258
     259This should generate all scripts necessary to run servers, clients,
     260etc.
     261
     262Starting ZEO servers and clients
     263================================
     264
     265First start the server::
     266
     267  $ ./bin/zeo_server start
     268
     269Clients can be started by doing::
     270
     271  $ ./bin/zeo_client1 start
     272  $ ./bin/zeo_client2 start
     273
     274This will start both clients in daemon mode.
     275
     276Instead of ``start`` you can, as usually, start an instance in
     277foreground (``fg``), etc. You know the drill.
     278
     279
     280Manually starting ZEO clients
     281=============================
     282
     283This is normally not neccessary.
     284
     285``zeo_clientN`` scripts are basically wrappers around calls to
     286``bin/paster``. You can bypass this wrapper and start a client
     287'manually' like this::
     288
     289  $ ./bin/paster serve --pid-file var/zeo1.pid --daemon \
     290        pars/etc/zeo1.ini
     291
     292It is important to give a pid-file as paster otherwise can not start
     293different clients (they would all refer to the same pid file
     294`paster.pid` and refuse to start after the first client was started).
     295
     296
     297Setup (paramters, ports, etc.)
     298==============================
     299
     300By default the server will listen on port 8100 for requests from
     301localhost (not: from the outside world).
     302
     303You can change ZEO server settings in the ``[zeo_server]`` section
     304of ``buildout-zeo.conf``. Run `buildout` afterwards.
     305
     306The clients will listen on port 8081 and 8082. You can change settings
     307in ``etc/zeo1.ini.in`` and ``etc/zeo2.ini.in`` respectively. Run
     308buildout after any change.
     309
     310If you want to change the paster wrapper for any zeo client, you can
     311edit ``etc/zeo1.conf`` and/or ``etc/zeo2.conf``. Run buildout
     312afterwards.
     313
     314
     315Creating new clients
     316====================
     317
     318You want more clients to be created by buildout? Easy. Three steps are
     319neccessary.
     320
     3211. Create config files in etc/
     322------------------------------
     323
     324Each client needs two configuration files:
     325
     326  - ``etc/zeoN.conf``
     327       configuring the paster wrapper
     328
     329  - ``etc/zeoN.ini``
     330       configuring the runtime config, ports, etc.
     331
     332Just copy over these files from the already existing zeo1/zeo2 files
     333and replace ``zeo1`` or ``zeo2`` with your new name.
     334
     3352. Update buildout-zeo.cfg
     336--------------------------
     337
     338Here, inside ``buildourt-zeo.cfg`` also three steps are needed.
     339
     340* 2.1. Create new .ini and .conf entries
     341
     342  The .conf and .ini files in etc/ are only templates that have to be
     343  generated in their really used final location. In buildout-zeo.cfg
     344  you can care for this by creating a new ``[zeoN_ini]`` and
     345  ``[zeoN_conf]`` option (replacing ``N`` with a number, of course).
     346
     347  Just copy over existing entries and replace the mentions of ``zeo1``
     348  or ``zeo2`` by your ``zeoN``.
     349
     350* 2.2. Create a new ``zeo_clientN`` entry
     351
     352  Then you have to create an entry that will generate the
     353  ``zeo_clientN`` script. Again, just copy over an existing
     354  ``[zeo_client1]`` entry and replace ``1`` withg your client number.
     355
     356* 2.3. Register the new sections in ``[buildout]`` section
     357
     358  When done with the above: add the new section in ``[buildout]``::
     359
     360    [buildout]
     361      ...
     362      <old entries...>
     363      ...
     364      zope_conf_zeo_5
     365      zeo5_ini
     366      zeo_client5
     367
     368  depending on how you named your new sections.
     369
     3703. Rerun ``buildout``
     371---------------------
     372
     373When adding or removing client/server instances, make sure to stop all
     374running servers/clients before rerunning buildout.
     375
     376To activate the new setup, rerun buildout::
     377
     378  $ bin/buildout -c buildout-zeo.cfg
     379
     380This should generate any new clients and remove older ones or just
     381update configuration files.
     382
     383
     384Considerations
     385==============
     386
     387There are some things in the current buildout-zeo.cfg we might do not
     388want. It extends the regular ``buildout.cfg`` so that we do not have
     389to repeat most sections but the ``parts`` in ``[buildout]`` have to be
     390listed.
     391
     392We need, however, not everything with a ZEO-deploy that is listed in a
     393default buildout. We might do not need docs, no profiling, etc. Also a
     394regular non-ZEO kofactl might not make to much sense. Therefore all
     395this might be subject to changes.
Note: See TracChangeset for help on using the changeset viewer.