Installation of Kofa
####################

These are generic installation instructions for the WAeUP.Kofa
student information portal and customized versions thereof.

For specific aspects of this package please refer to the local README
file.

Please note, that **only Linux-based installs** are described and actively
supported. We recommend use of Debian_ / Ubuntu_.

.. note:: This means we do not actively support Windows(tm)!

.. contents:: Table of Contents
   :local:


Prerequisites
*************

The Kofa packages are based on `Grok`_, which is a Python_
framework for agile web application development. Grok_ itself is based
on `Zope`_.

Both, Grok_ and Zope_, are written in the `Python`_ programming
language (with parts written in C). You therefore have to have
`Python`_ installed (including `Python`_ headers) in version 2.7
(Python 3.x is currently not supported).


Quick Install on Ubuntu 20.04 or 22.04
**************************************

If you want to install Kofa on an Ubuntu system, the following quick
steps might be sufficient::

  ## install neccessary system packages as superuser

  $ sudo apt-get update && apt-get install -y tzdata
  $ sudo apt-get install -y apt-utils build-essential
  $ sudo apt-get install -y python2.7-dev libxml2-dev libxslt1-dev \
                         zlib1g-dev python3-virtualenv
  # see https://urllib3.readthedocs.org/en/latest/security.html#openssl-pyopenssl
  $ sudo apt-get install -y libssl-dev libffi-dev
  # libs needed/useful for Pillow image manipulations
  $ sudo apt-get install -y libjpeg-dev libfreetype6-dev libtiff-dev libopenjp2-7-dev

  ## add user `kofa`

  $ sudo useradd -ms /bin/bash kofa
  # set password of user `kofa` and add to group 'sudo'
  $ sudo echo kofa:kofa | chpasswd && adduser kofa sudo
  # proceed as user `kofa`

  ## proceed as user `kofa`

  $ sudo su kofa
  $ cd /home/kofa

  ## create python sandbox and install packages inside

  $ virtualenv -p /usr/bin/python2.7 py27
  $ source py27/bin/activate
  # pin down `pip` and `setuptools` - just to ensure we have a fixed set of versions
  (py27)$ py27/bin/pip install --upgrade pip==20.3.4
  (py27)$ py27/bin/pip install --upgrade --force-reinstall setuptools==44.1.1
  # pin down `zc.buildout` - versions >= 3 make entry-points of installed eggs
  # invisible for `pgk_resources`
  (py27)$ py27/bin/pip install "zc.buildout<3"
  (py27)$ deactivate

  ## get sources

  # we can work with official PyPI sources...
  $ py27/bin/pip download --no-deps waeup.kofa==1.8 && tar -xzf waeup.kofa-1.8.tar.gz
  $ mv waeup.kofa-1.8 waeup.kofa
  $ cd waeup.kofa

  ## build Kofa

  $ ../py27/bin/buildout

  ## startup Kofa in foreground

  $ bin/kofactl fg
  # press CTRL-D to stop the kofa server

  ## startup Kofa in background

  $ bin/kofactl start
  $ bin/kofactl status  # check status, running or not
  $ bin/kofactl stop    # stop running instance (also 'restart' possible)

When Kofa is running, you can access the portal on port 8080:

http://localhost:8080/

Enter the credentials (username 'grok', password 'grok' by default)
and name and add a `University`.

Congratulations, you got Kofa running.



.. _Debian: http://www.debian.org/
.. _Grok: http://grok.zope.org/
.. _Python: http://www.python.org/
.. _Subversion: http://subversion.apache.org/
.. _Ubuntu: http://www.ubuntu.com/
.. _virtualenv: http://www.virtualenv.org/en/latest/
.. _WAeUP: https://www.waeup.org/
.. _Zope: http://www.zope.org/
.. _zc.buildout: http://cheeseshop.python.org/pypi/zc.buildout