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

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
*************

Installing `kofa` from sources on a local system involves many steps to meet
all requirements, dependencies, etc. For quick setup we provide `docker`_
based installs which ease the whole setup procedure very much.

There are, however, a few things, you should be aware of. Most important:
`kofa` stores persistent data on disk, in an own `var/` directory. This
directory keeps all files, database data and also log files. You must keep this
directory if you want to keep your data.

Starting with version 1.8, each release of `kofa` contains a `Dockerfile` in
the sources root. You can use this file to build a dockerized version of
`kofa`. But you can also use this file as a reference, how to build `kofa` from
sources.

Good to know and very important if you want to install the manual way:
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). For a source install you therefore have to have `Python`_
installed (including `Python`_ headers) in version 2.7 (Python 3.x is currently
not supported).

If you want to install using `docker` you of course need `docker` installed on
your system. Please refer to your system documentation or to https://docker.com
for details.


Quick Install (dockerized)
**************************

The Dockerfiles contained in our releases fetch sources from the central Python
package repository `https://pypi.org/`. Visit the Dockerfile to learn, how you
can build kofa from a local source tree.

Go to the directory with the `Dockerfile` (we assume here, it is called
`waeup.kofa`)::

  $ cd waeup.kofa

You might want to create a `var/` directory to keep the persisted data later::

  $ mkdir var/

Build `kofa` and tag the build, so you can tell different versions apart later
on::

  $ docker build -t kofa:latest .

Please note the separated dot at the end of the command.

Replace `kofa:latest` with any tag you find useful. Usual alternative tags
would be: `kofa:1.8.1.dev0` or similar. But also `mybuild:foo` or just
`mybuild` are valid tags.

This command will take a lot of time and will perform all the steps, you would
need to do to install `kofa` natively.

If all works well, you can start a new `kofa` instance in foreground like this::

  $ docker run --rm -it -p 8080:8080 -v kofadata1:/home/kofa/waeup.kofa/var kofa:latest

Use the tag you picked before (here: `kofa:latest`) and connect to the running instance

https://localhost:8080/

Your username and password will be `grok` and `grok`.

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

Congratulations, you got Kofa running.


What else can I do with `kofa` and Docker?
******************************************

Some remarks about the last `docker` command:
`-v kofadata1:/home/kofa/waeup.kofa` keeps a persistent volume named `kofadata1` on
your host. You do not have to know where this volume resides on your machine
(while you can, if you insist). The containers using this volume can be
discarded after use and you can of course keep multiple volumes in parallel on
your system.

You can stop the instance running in foreground pressing `CTRL-C`.

Passing `--rm` to `docker` means to dispose a container after it stopped.


Run `kofa` daemonized
*********************

If you want to run `kofa` daemonized, use this::

  $ docker run --rm -d -p 8080:8080 -v kofadata1:/home/kofa/waeup.kofa/var kofa:latest

Instead of interactive (`-it`) we now use daemonized mode (`-d`). We also
tunnel the containers port 8080 to our hosts port 8080 because otherwise we
could not reach `kofa`. For security reasons it binds to containers localhost
address by default.

You can stop this instance with::

   $ docker stop kofa:latest

which will stop and destroy the running container. If you create a new
container with the same volume data, all objects from the last run should be
visible and usable.


Enter the `kofa` filesystem inside container
********************************************

If an instance is running, you can enter the filesystem with for instance::

   $ docker run --rm -it -v kofadata1:/home/kofa/waeup.kofa/var kofa:latest /bin/bash

which will drop you into a shell inside the container. Your system credentials
are by default `kofa` and `kofa`.


Copy data in and out of the container
*************************************

For backups etc. it is essential that you can copy data from or to the
container. To do this, we mount a second local directory into the container and
use that for transmitting data::

  $ mkdir mybackup
  $ docker run --rm -it -v kofadata1:/home/kofa/waeup.kofa/var -v `pwd`/mybackup:/data kofa:latest cp -ar /home/kofa/waeup.kofa/var /mybackup

which will copy the whole container-internal `var/`-directory into our local
`mybackup` dir.


How to start/stop `kofa` when running the native setup
******************************************************

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)

That should start you.

Have fun with Kofa!


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