Changeset 17263


Ignore:
Timestamp:
10 Jan 2023, 14:12:55 (21 months ago)
Author:
Henrik Bettermann
Message:

Update installation guide.

File:
1 edited

Legend:

Unmodified
Added
Removed

  • main/waeup.kofa/trunk/docs/INSTALL.txt

    r15892 r17263  
    22####################
    33
    4 These are generic installation instructions for the WAeUP_ Kofa
     4These are generic installation instructions for the WAeUP.Kofa
    55student information portal and customized versions thereof.
    66
    … …  
    1515.. contents:: Table of Contents
    1616   :local:
    17 
    18 .. _prerequisites:
    19 
    20 
    21 Quick Install on Ubuntu 18.04
    22 *****************************
    23 
    24 If you want to install Kofa on a running Ubuntu system, the following quick
    25 steps might be sufficient::
    26 
    27   ## install neccessary system packages as superuser
    28   $ sudo apt-get update && apt-get install -y  # update system
    29   $ sudo apt-get install python2.7-dev libxml2-dev libxslt1-dev zlib1g-dev python-virtualenv libssl-dev libffi-dev libjpeg-dev libfreetype6-dev libtiff-dev libopenjp2-7-dev
    30 
    31   ## get sources as regular user
    32   $ wget https://pypi.python.org/packages/ed/0f/0b30fcf8c113b11967c1481668b38b4b9e32f256eb366f73b70ff960872f/waeup.kofa-1.5.tar.gz && tar -xzf waeup.kofa-1.5.tar.gz
    33   $ cd waeup.kofa-1.5
    34 
    35   ## create python sandbox and build kofa
    36   $ virtualenv py27
    37   $ source py27/bin/activate
    38   $ pip install --upgrade pip
    39   $ python bootstrap.py
    40   $ ./bin/buildout
    41 
    42 To run Kofa, now do::
    43 
    44   ## startup Kofa in foreground (recommended for first start)
    45   $ ./bin/kofactl fg
    46   ## press CTRL-D to stop the kofa server
    47 
    48   ## startup Kofa in background
    49   $ ./bin/kofactl start
    50   $ ./bin/kofactl status  # check status, running or not
    51   $ ./bin/kofactl stop    # stop running instance (also 'restart' possible)
    52 
    53 When Kofa is running, you can access the portal on port 8080. Open
    54 
    55   http://localhost:8080/
    56 
    57 and enter the credentials (username 'grok', password 'grok' by
    58 default) and name and add a `University`.
    59 
    60 Congratulations, you got Kofa running.
    6117
    6218
    … …  
    7430
    7531
    76 Preparing the System
    77 ====================
     32Quick Install on Ubuntu 20.04 or 22.04
     33**************************************
    7834
    79 For a Kofa install we need of course `Python`_ installed as well as
    80 some standard developer tools like C compilers, C libraries, etc.
     35If you want to install Kofa on an Ubuntu system, the following quick
     36steps might be sufficient::
    8137
    82 What you need (Debian/Ubuntu package names in brackets):
     38  ## install neccessary system packages as superuser
    8339
    84 * Python 2.7 (``python2.7``)
     40  $ sudo apt-get update && apt-get install -y tzdata
     41  $ sudo apt-get install -y apt-utils build-essential
     42  $ sudo apt-get install -y python2.7-dev libxml2-dev libxslt1-dev \
     43                         zlib1g-dev python3-virtualenv
     44  # see https://urllib3.readthedocs.org/en/latest/security.html#openssl-pyopenssl
     45  $ sudo apt-get install -y libssl-dev libffi-dev
     46  # libs needed/useful for Pillow image manipulations
     47  $ sudo apt-get install -y libjpeg-dev libfreetype6-dev libtiff-dev libopenjp2-7-dev
    8548
    86 * Python 2.7 development files (``python2.7-dev``)
     49  ## add user `kofa`
    8750
    88 * A C-Compiler with basic C developer libraries (``build-essential``)
     51  $ sudo useradd -ms /bin/bash kofa
     52  # set password of user `kofa` and add to group 'sudo'
     53  $ sudo echo kofa:kofa | chpasswd && adduser kofa sudo
     54  # proceed as user `kofa`
    8955
    90 * A subversion client (``subversion``)
     56  ## proceed as user `kofa`
    9157
    92 * XML and XSLT development libraries (``libxml2-dev``, ``libxslt1-dev``)
     58  $ sudo su kofa
     59  $ cd /home/kofa
    9360
    94 * Other helper libraries, especially for image processing support
    95   (``zlib1g-dev``, ``libssl-dev``, ``libffi-dev``, ``libjpeg-dev``,
    96   ``libfreetype6-dev``, ``libtiff-dev`` ``libopenjpeg-dev``)
     61  ## create python sandbox and install packages inside
    9762
    98 * enscript (``enscript``) [optional]
     63  $ virtualenv -p /usr/bin/python2.7 py27
     64  $ source py27/bin/activate
     65  # pin down `pip` and `setuptools` - just to ensure we have a fixed set of versions
     66  (py27)$ py27/bin/pip install --upgrade pip==20.3.4
     67  (py27)$ py27/bin/pip install --upgrade --force-reinstall setuptools==44.1.1
     68  # pin down `zc.buildout` - versions >= 3 make entry-points of installed eggs
     69  # invisible for `pgk_resources`
     70  (py27)$ py27/bin/pip install "zc.buildout<3"
     71  (py27)$ deactivate
    9972
    100   This is only needed if you want test coverage reports.
     73  ## get sources
    10174
    102 All these packages can be installed on Debian systems like this::
     75  # we can work with official PyPI sources...
     76  $ py27/bin/pip download --no-deps waeup.kofa==1.8 && tar -xzf waeup.kofa-1.8.tar.gz
     77  $ mv waeup.kofa-1.8 waeup.kofa
     78  $ cd waeup.kofa
    10379
    104   $ sudo apt-get install python2.7 python2.7-dev subversion \
    105                          build-essential enscript libxml2-dev libxslt1-dev \
    106                          zlib1g-dev libssl-dev libffi-dev libjpeg-dev \
    107                          libfreetype6-dev libtiff-dev libopenjpeg-dev
     80  ## build Kofa
    10881
    109 Afterwards you should be able to enter::
     82  $ ../py27/bin/buildout
    11083
    111   $ python2.7
     84  ## startup Kofa in foreground
    11285
    113 at the commandline and get a Python_ prompt. Quit the interpreter
    114 pressing <CTRL-D>.
     86  $ bin/kofactl fg
     87  # press CTRL-D to stop the kofa server
    11588
    116 The above packages have been tested to be sufficient for running Kofa
    117 on Ubuntu. We check this with Docker images created at
     89  ## startup Kofa in background
    11890
    119    https://github.com/WAeUP/kofa-docker
     91  $ bin/kofactl start
     92  $ bin/kofactl status  # check status, running or not
     93  $ bin/kofactl stop    # stop running instance (also 'restart' possible)
    12094
    121 This project provides tags that refer to certain Kofa versions.
     95When Kofa is running, you can access the portal on port 8080:
    12296
    123 Please note: to make freetype2 work correctly with Kofa [#]_, you have to
    124 fix a link::
     97http://localhost:8080/
    12598
    126   (root) $  ln -s /usr/include/freetype2 /usr/include/freetype2/freetype
     99Enter the credentials (username 'grok', password 'grok' by default)
     100and name and add a `University`.
     101
     102Congratulations, you got Kofa running.
    127103
    128104
    129 
    130 
    131 Installing `virtualenv`
    132 =======================
    133 
    134 We strongly suggest use of `virtualenv`_ to create Python_ sandboxes
    135 where you can run your code without touching any other installations.
    136 
    137 `virtualenv`_ is also the only possibility to build a Kofa install
    138 without the need of superuser permissions. In short: `virtualenv`_
    139 will make your life easier. Use it.
    140 
    141 Detailed install instructions for `virtualenv`_ can be found on
    142 http://www.virtualenv.org/en/latest/virtualenv.html#installation.
    143 
    144 The short way for a user install (no superuser perms required) is like
    145 this::
    146 
    147   $ curl -O https://pypi.python.org/packages/source/v/virtualenv/virtualenv-1.11.4.tar.gz#md5=9accc2d3f0ec1da479ce2c3d1fdff06e
    148   $ tar xvfz virtualenv-1.11.4.tar.gz
    149   $ cd virtualenv-1.11.4
    150   $ python virtualenv.py py27
    151 
    152 Superusers can install `virtualenv`_ system-wide much easier. On
    153 `Debian`_/`Ubuntu`_ systems where you have superuser permissions, you
    154 can install `virtualenv`_ via::
    155 
    156   $ sudo apt-get install python-virtualenv
    157 
    158 *Or*, they install if `pip` first::
    159 
    160   $ sudo apt-get install python-pip
    161 
    162 and then use `pip` to install `virtualenv`_::
    163 
    164   $ sudo pip install virtualenv
    165 
    166 
    167 Creating a Sandbox
    168 ==================
    169 
    170 After installing `virtualenv`_ you can install local sandboxes like
    171 this (if `virtualenv` is installed system-wide)::
    172 
    173   $ virtualenv --no-site-packages py27
    174 
    175 *or* like this::
    176 
    177   $ python /path/to/my/virtualenv.py --no-site-packages py27
    178 
    179 where ``py27`` is a directory in the filesystem where your sandbox
    180 will be created. `virtualenv` will also create this directory for
    181 you. While you can pick any sandbox name you want, it is recommended
    182 to use a sandbox name that is short and at the same time reflects the
    183 Python version used (here: Python 2.7).
    184 
    185 By passing the ``no-site-packages`` switch we tell `virtualenv` to
    186 provide a clean environment without any extra-packages installed
    187 systemwide. More recent versions of `virtualenv`_ have this option set
    188 by default.
    189 
    190 Another often used option of `virtualenv`_ is ``-p``. With ``-p`` you
    191 can tell `virtualenv`_ which Python executable to use as base for the
    192 new sandbox.
    193 
    194 You now can activate the sandbox by doing::
    195 
    196   $ source py27/bin/activate
    197   (py27)$
    198 
    199 You will notice that the input prompt changes, indicating the name of
    200 the sandbox activated.
    201 
    202 To deactivate the sandbox at any time, enter::
    203 
    204   (py27)$ deactivate
    205 
    206 and the prompt will be the same as before the activation.
    207 
    208 For the following steps make sure the sandbox is active.
    209 
    210 
    211 Getting the Sources
    212 ===================
    213 
    214 Now, as the sandbox is activated (see above, if not), we can fetch the
    215 sources for Kofa.
    216 
    217 Source from PyPI
    218 ----------------
    219 
    220 Official releases are always uploaded to PyPI. Please have a look at
    221 
    222   http://pypi.python.org/pypi/waeup.kofa
    223 
    224 where you can download all you need.
    225 
    226 From the commandline you can also get sources like this::
    227 
    228   (py27)$ wget https://pypi.python.org/packages/source/w/waeup.kofa/waeup.kofa-1.5.tar.gz
    229 
    230 where ``1.5`` is, of course, only one possible version.
    231 
    232 
    233 Source from Subversion
    234 ----------------------
    235 
    236 If you have access to the (restricted) developer repository (if you
    237 don't know, then you have not), then you can use the Subversion_
    238 client `svn` and checkout the main devel branch of the `waeup.kofa`
    239 package like this::
    240 
    241   (py27)$ svn co https://svn.waeup.org/repos/main/waeup.kofa/trunk
    242 
    243 The command should fetch the Kofa base package sources for you and
    244 will put everything in a new directory ``trunk/``.
    245 
    246 Now enter the new directory::
    247 
    248   (py27)$ cd trunk/
    249 
    250 and you can start building the real package.
    251 
    252 .. note:: If you not want to work with the `waeup.kofa` package but a
    253           customized package (like ``waeup.aaue`` or similar), then
    254           you can use the above checkout command but with
    255           ``waeup.kofa`` replaced by the name of the customized
    256           package::
    257 
    258             (py27)$ svn co https://svn.waeup.org/repos/main/<PKG-NAME>/trunk
    259 
    260           For the exact link, please refer to the README.txt file in
    261           your package.
    262 
    263 
    264 Bootstrapping the Build
    265 =======================
    266 
    267 After `Creating a Sandbox`_ and `Getting the Sources`_ we have to
    268 initialize the newly created development environment::
    269 
    270   (py27)$ python bootstrap.py
    271 
    272 This should create a local ``bin/`` directory with at least a script
    273 ``buildout`` in it.
    274 
    275 If bootstrapping fails, chances are, that you need the `distribute`
    276 package installed. In a virtual environment you can install it without
    277 interfering with other packages installed on your server::
    278 
    279   (py27)$ pip install --upgrade distribute
    280 
    281 Afterwards you have to retry the bootstrapping, until you get a
    282 working ``buildout`` script in the local ``bin/`` directory.
    283 
    284 Once the ``buildout`` script exists, you do not have to activate the
    285 virtual envronment any more (although you can).
    286 
    287 
    288 Part 1: Single Client Setup
    289 ***************************
    290 
    291 You can run Kofa with a single client (useful for evaluation,
    292 development, etc.) or with multiple clients running in parallel. The
    293 latter setup is useful in productive environments with many thousands
    294 users and called a ``ZEO`` install. We will cover both setup
    295 types. The first is covered here, the latter one is covered in `Part
    296 2: ZEO Install`_.
    297 
    298 
    299 Building the Package
    300 ====================
    301 
    302 In the sources directory (``trunk/``) you have to prepare the
    303 project to fetch needed components (eggs), compile C-code parts,
    304 etc. This is done by a single command ``buildout``::
    305 
    306   $ ./bin/buildout
    307 
    308 If this is your first install of some Grok-related project, this step
    309 will need some time as lots of sources have to be fetched, many
    310 components must be compiled, etc.
    311 
    312 This step must be redone whenever you change something in
    313 ``buildout.cfg``, ``buildout-zeo.cfg``, or ``setup.py``.
    314 
    315 Note that if you have more than one sandbox for a Zope-based web
    316 application, it will probably make sense to share the eggs between the
    317 different sandboxes.  You can tell ``zc.buildout`` to use a central
    318 eggs directory by creating ``~/.buildout/default.cfg`` with the
    319 following contents::
    320 
    321   [buildout]
    322   eggs-directory = /home/bruno/buildout-eggs
    323 
    324 where the given directory should be exist beforehand. All eggs of all
    325 `buildout` projects will then be stored in this directory (and not
    326 fetched anew if already existing there).
    327 
    328 
    329 Start the Instance
    330 ==================
    331 
    332 You should be able now to start the created instance by doing::
    333 
    334   $ ./bin/kofactl fg
    335 
    336 Alternatively you can do::
    337 
    338   $ bin/paster serve parts/etc/deploy-themed.ini
    339 
    340 The port numbers where Kofa is running on your server are defined in
    341 `buildout.cfg` under ``[kofa_params]``.
    342 
    343 If you now point a browser to the right port on your server, for example::
    344 
    345   localhost:8080
    346 
    347 you should get a login pop-up, where you can login as superuser with
    348 ``grok`` and ``grok`` as username/password (Kofa base package only!).
    349 
    350 You can stop the instance by pressing <CTRL-C>.
    351 
    352 If you are connected and logged in,
    353 you should be able to add the grok-based applications
    354 (such as ``University``) from the menu.
    355 
    356 Add an instance of ``University`` and click on the link next to the
    357 then visible entry in the list of installed applications.
    358 
    359 Running the Tests
    360 =================
    361 
    362 All WAeUP_ packages come with comprehensive test suites ensuring the
    363 software quality also after changes and updates.
    364 
    365 The package tests are easily run by executing the test runner
    366 from the ``bin`` directory::
    367 
    368   $ ./bin/test
    369 
    370 Use the ``-c`` option to get coloured output. Use the ``--pdb`` option
    371 to start the Python_ debugger when a test fails.
    372 
    373 
    374 Part 2: ZEO Install
    375 *******************
    376 
    377 Each ZEO install consists of at least one ZEO server and normally two
    378 or more ZEO clients. While the ZEO server is meant to manage the ZODB
    379 database for clients, the clients connect to the outside world, listen
    380 for request and do the real dataprocessing.
    381 
    382 We prepared a `buildout` configuration that sets up one server
    383 configuration and two client configs. This configuration is in
    384 ``buildout-zeo.cfg``.
    385 
    386 Generating the ZEO Setup
    387 ========================
    388 
    389 To install Kofa ZEO-based you can run `buildout` with the given
    390 (or your own) configuration file like this::
    391 
    392   $ ./bin/buildout -c buildout-zeo.cfg
    393 
    394 This should generate all scripts necessary to run servers, clients,
    395 etc.
    396 
    397 Starting ZEO Servers and Clients
    398 ================================
    399 
    400 First start the server::
    401 
    402   $ ./bin/zeo_server start
    403 
    404 Clients can be started by doing::
    405 
    406   $ ./bin/zeo_client1 start
    407   $ ./bin/zeo_client2 start
    408 
    409 This will start both clients in daemon mode.
    410 
    411 Instead of ``start`` you can, as usually, start an instance in
    412 foreground (``fg``), etc. You know the drill.
    413 
    414 
    415 Manually Starting ZEO Clients
    416 =============================
    417 
    418 This is normally not neccessary.
    419 
    420 ``zeo_clientN`` scripts are basically wrappers around calls to
    421 ``bin/paster``. You can bypass this wrapper and start a client
    422 'manually' like this::
    423 
    424   $ ./bin/paster serve --pid-file var/zeo1.pid --daemon \
    425         pars/etc/zeo1.ini
    426 
    427 It is important to give a pid-file as `paster` otherwise can not start
    428 different clients (they would all refer to the same pid file
    429 `paster.pid` and refuse to start after the first client was started).
    430 
    431 
    432 Setup (parameters, ports, etc.)
    433 ===============================
    434 
    435 By default the server will listen on port 8100 for requests from
    436 localhost (not: from the outside world).
    437 
    438 You can change ZEO server settings in the ``[zeo_server]`` section
    439 of ``buildout-zeo.conf``. Run `buildout` afterwards.
    440 
    441 The clients will listen on port 8081 and 8082. You can change settings
    442 in ``etc/zeo1.ini.in`` and ``etc/zeo2.ini.in`` respectively. Run
    443 buildout after any change.
    444 
    445 If you want to change the paster wrapper for any zeo client, you can
    446 edit ``etc/zeo1.conf`` and/or ``etc/zeo2.conf``. Run buildout
    447 afterwards.
    448 
    449 
    450 Stopping ZEO Servers and Clients
    451 ================================
    452 
    453 Given everything was started in daemon mode, first stop the clients::
    454 
    455   $ ./bin/zeo_client1 stop
    456   $ ./bin/zeo_client2 stop
    457 
    458 Then stop the ZEO server::
    459 
    460   $ ./bin/zeo_server stop
    461 
    462 
    463 Creating New ZEO Clients
    464 ========================
    465 
    466 You want more ZEO clients to be created by `buildout`? Easy. Three
    467 steps are neccessary.
    468 
    469 1. Create config files in `etc/`
    470 --------------------------------
    471 
    472 Each client needs two configuration files:
    473 
    474   - ``etc/zeoN.conf``
    475        configuring the paster wrapper
    476 
    477   - ``etc/zeoN.ini``
    478        configuring the runtime config, ports, etc.
    479 
    480 Just copy over these files from the already existing zeo1/zeo2 files
    481 and replace ``zeo1`` or ``zeo2`` with your new name.
    482 
    483 2. Update buildout-zeo.cfg
    484 --------------------------
    485 
    486 Here, inside ``buildourt-zeo.cfg`` also three steps are needed.
    487 
    488 * 2.1. Create new .ini and .conf entries
    489 
    490   The .conf and .ini files in etc/ are only templates that have to be
    491   generated in their really used final location. In buildout-zeo.cfg
    492   you can care for this by creating a new ``[zeoN_ini]`` and
    493   ``[zeoN_conf]`` option (replacing ``N`` with a number, of course).
    494 
    495   Just copy over existing entries and replace the mentions of ``zeo1``
    496   or ``zeo2`` by your ``zeoN``.
    497 
    498 * 2.2. Create a new ``zeo_clientN`` entry
    499 
    500   Then you have to create an entry that will generate the
    501   ``zeo_clientN`` script. Again, just copy over an existing
    502   ``[zeo_client1]`` entry and replace ``1`` withg your client number.
    503 
    504 * 2.3. Register the new sections in ``[buildout]`` section
    505 
    506   When done with the above: add the new section in ``[buildout]``::
    507 
    508     [buildout]
    509       ...
    510       <old entries...>
    511       ...
    512       zope_conf_zeo_5
    513       zeo5_ini
    514       zeo_client5
    515 
    516   depending on how you named your new sections.
    517 
    518 3. Rerun ``buildout``
    519 ---------------------
    520 
    521 When adding or removing client/server instances, make sure to stop all
    522 running servers/clients before rerunning buildout.
    523 
    524 To activate the new setup, rerun buildout::
    525 
    526   $ bin/buildout -c buildout-zeo.cfg
    527 
    528 This should generate any new clients and remove older ones or just
    529 update configuration files.
    530 
    531 
    532 Considerations
    533 ==============
    534 
    535 There are some things in the current buildout-zeo.cfg we might do not
    536 want. It extends the regular ``buildout.cfg`` so that we do not have
    537 to repeat most sections but the ``parts`` in ``[buildout]`` have to be
    538 listed.
    539 
    540 We need, however, not everything with a ZEO-deploy that is listed in a
    541 default buildout. We might do not need docs, no profiling, etc. Also a
    542 regular non-ZEO kofactl might not make to much sense. Therefore all
    543 this might be subject to changes.
    544105
    545106.. _Debian: http://www.debian.org/
    … …  
    552113.. _Zope: http://www.zope.org/
    553114.. _zc.buildout: http://cheeseshop.python.org/pypi/zc.buildout
    554 .. [#] Strictly speaking, this link fix is required by ``Pillow``, a
    555    library used by Kofa to provide higher-level image processing.
     115
Note: See TracChangeset for help on using the changeset viewer.