source: main/waeup.ikoba/trunk/docs/INSTALL.txt @ 17225

Last change on this file since 17225 was 12332, checked in by uli, 10 years ago

Tell about libssl requirement.

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