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)!

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

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 /data

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!