Ignore:
Timestamp:
11 Jan 2023, 06:25:47 (2 years ago)
Author:
uli
Message:

dockerize kofa

File:
1 edited

Legend:

Unmodified
Added
Removed

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

    r17263 r17264  
    2020*************
    2121
     22Installing `kofa` from sources on a local system involves many steps to meet
     23all requirements, dependencies, etc. For quick setup we provide `docker`_
     24based installs which ease the whole setup procedure very much.
     25
     26There are, however, a few things, you should be aware of. Most important:
     27`kofa` stores persistent data on disk, in an own `var/` directory. This
     28directory keeps all files, database data and also log files. You must keep this
     29directory if you want to keep your data.
     30
     31Starting with version 1.8, each release of `kofa` contains a `Dockerfile` in
     32the sources root. You can use this file to build a dockerized version of
     33`kofa`. But you can also use this file as a reference, how to build `kofa` from
     34sources.
     35
     36Good to know and very important if you want to install the manual way:
    2237The Kofa packages are based on `Grok`_, which is a Python_
    2338framework for agile web application development. Grok_ itself is based
    2439on `Zope`_.
    2540
    26 Both, Grok_ and Zope_, are written in the `Python`_ programming
    27 language (with parts written in C). You therefore have to have
    28 `Python`_ installed (including `Python`_ headers) in version 2.7
    29 (Python 3.x is currently not supported).
     41Both, Grok_ and Zope_, are written in the `Python`_ programming language (with
     42parts written in C). For a source install you therefore have to have `Python`_
     43installed (including `Python`_ headers) in version 2.7 (Python 3.x is currently
     44not supported).
     45
     46If you want to install using `docker` you of course need `docker` installed on
     47your system. Please refer to your system documentation or to https://docker.com
     48for details.
    3049
    3150
    32 Quick Install on Ubuntu 20.04 or 22.04
    33 **************************************
     51Quick Install (dockerized)
     52**************************
    3453
    35 If you want to install Kofa on an Ubuntu system, the following quick
    36 steps might be sufficient::
     54The Dockerfiles contained in our releases fetch sources from the central Python
     55package repository `https://pypi.org/`. Visit the Dockerfile to learn, how you
     56can build kofa from a local source tree.
    3757
    38   ## install neccessary system packages as superuser
     58Go to the directory with the `Dockerfile` (we assume here, it is called
     59`waeup.kofa`)::
    3960
    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
    48 
    49   ## add user `kofa`
    50 
    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`
    55 
    56   ## proceed as user `kofa`
    57 
    58   $ sudo su kofa
    59   $ cd /home/kofa
    60 
    61   ## create python sandbox and install packages inside
    62 
    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
    72 
    73   ## get sources
    74 
    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
    7861  $ cd waeup.kofa
    7962
    80   ## build Kofa
     63You might want to create a `var/` directory to keep the persisted data later::
    8164
    82   $ ../py27/bin/buildout
     65  $ mkdir var/
     66
     67Build `kofa` and tag the build, so you can tell different versions apart later
     68on::
     69
     70  $ docker build -t kofa:latest .
     71
     72Please note the separated dot at the end of the command.
     73
     74Replace `kofa:latest` with any tag you find useful. Usual alternative tags
     75would be: `kofa:1.8.1.dev0` or similar. But also `mybuild:foo` or just
     76`mybuild` are valid tags.
     77
     78This command will take a lot of time and will perform all the steps, you would
     79need to do to install `kofa` natively.
     80
     81If all works well, you can start a new `kofa` instance in foreground like this::
     82
     83  $ docker run --rm -it -p 8080:8080 -v kofadata1:/home/kofa/waeup.kofa/var kofa:latest
     84
     85Use the tag you picked before (here: `kofa:latest`) and connect to the running instance
     86
     87https://localhost:8080/
     88
     89Your username and password will be `grok` and `grok`.
     90
     91Enter the credentials (username 'grok', password 'grok' by default)
     92and name and add a `University`.
     93
     94Congratulations, you got Kofa running.
     95
     96
     97What else can I do with `kofa` and Docker?
     98******************************************
     99
     100Some remarks about the last `docker` command:
     101`-v kofadata1:/home/kofa/waeup.kofa` keeps a persistent volume named `kofadata1` on
     102your host. You do not have to know where this volume resides on your machine
     103(while you can, if you insist). The containers using this volume can be
     104discarded after use and you can of course keep multiple volumes in parallel on
     105your system.
     106
     107You can stop the instance running in foreground pressing `CTRL-C`.
     108
     109Passing `--rm` to `docker` means to dispose a container after it stopped.
     110
     111
     112Run `kofa` daemonized:
     113**********************
     114
     115If you want to run `kofa` daemonized, use this::
     116
     117  $ docker run --rm -d -p 8080:8080 -v kofadata1:/home/kofa/waeup.kofa/var kofa:latest
     118
     119Instead of interactive (`-it`) we now use daemonized mode (`-d`). We also
     120tunnel the containers port 8080 to our hosts port 8080 because otherwise we
     121could not reach `kofa`. For security reasons it binds to containers localhost
     122address by default.
     123
     124You can stop this instance with::
     125
     126   $ docker stop kofa:latest
     127
     128which will stop and destroy the running container. If you create a new
     129container with the same volume data, all objects from the last run should be
     130visible and usable.
     131
     132
     133Enter the `kofa` filesystem inside container
     134********************************************
     135
     136If an instance is running, you can enter the filesystem with for instance:
     137
     138   $ docker run --rm -it -v kofadata1:/home/kofa/waeup.kofa/var kofa:latest /bin/bash
     139
     140which will drop you into a shell inside the container. Your system credentials
     141are by default `kofa` and `kofa`.
     142
     143
     144Copy data in and out of the container
     145*************************************
     146
     147For backups etc. it is essential that you can copy data from or to the
     148container. To do this, we mount a second local directory into the container and
     149use that for transmitting data:
     150
     151  $ mkdir mybackup
     152  $ 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
     153
     154which will copy the whole container-internal `var/`-directory into our local
     155`mybackup` dir.
     156
     157
     158How to start/stop `kofa` when running the native setup
     159******************************************************
    83160
    84161  ## startup Kofa in foreground
    … …  
    93170  $ bin/kofactl stop    # stop running instance (also 'restart' possible)
    94171
    95 When Kofa is running, you can access the portal on port 8080:
     172That should start you.
    96173
    97 http://localhost:8080/
    98 
    99 Enter the credentials (username 'grok', password 'grok' by default)
    100 and name and add a `University`.
    101 
    102 Congratulations, you got Kofa running.
     174Have fun with Kofa!
    103175
    104176
    105177
    106 .. _Debian: http://www.debian.org/
     178.. _Debian: https://www.debian.org/
     179.. _docker: https://
    107180.. _Grok: http://grok.zope.org/
    108 .. _Python: http://www.python.org/
    109 .. _Subversion: http://subversion.apache.org/
    110 .. _Ubuntu: http://www.ubuntu.com/
    111 .. _virtualenv: http://www.virtualenv.org/en/latest/
     181.. _Python: https://www.python.org/
     182.. _Subversion: https://subversion.apache.org/
     183.. _Ubuntu: https://www.ubuntu.com/
     184.. _virtualenv: https://www.virtualenv.org/en/latest/
    112185.. _WAeUP: https://www.waeup.org/
    113 .. _Zope: http://www.zope.org/
    114 .. _zc.buildout: http://cheeseshop.python.org/pypi/zc.buildout
     186.. _Zope: https://www.zope.org/
     187.. _zc.buildout: https://pypi.org/project/zc.buildout
    115188
Note: See TracChangeset for help on using the changeset viewer.