Changeset 17264 for main

Timestamp:

11 Jan 2023, 06:25:47 (21 months ago)

Author:

uli

Message:

dockerize kofa

Location:

main/waeup.kofa/trunk

Files:

• Dockerfile (added)
• MANIFEST.in (modified) (1 diff)
• docs/INSTALL.txt (modified) (2 diffs)

main/waeup.kofa/trunk/MANIFEST.in

@@ -6 +6 @@
 recursive-include etc *.in *.txt
 graft layout
-include *.cfg bootstrap.py CHANGES.txt LICENSE
+include *.cfg bootstrap.py CHANGES.txt LICENSE Dockerfile
 exclude .* uuid.txt
 global-exclude *~ *.pyc *.pyo

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

@@ -20 +20 @@
 *************
 
+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). You therefore have to have
-`Python`_ installed (including `Python`_ headers) in version 2.7
-(Python 3.x is currently not supported).
+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 on Ubuntu 20.04 or 22.04
-**************************************
+Quick Install (dockerized)
+**************************
 
-If you want to install Kofa on an Ubuntu system, the following quick
-steps might be sufficient::
+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.
 
-  ## install neccessary system packages as superuser
+Go to the directory with the `Dockerfile` (we assume here, it is called
+`waeup.kofa`)::
 
-  $ 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
+You might want to create a `var/` directory to keep the persisted data later::
 
-  $ ../py27/bin/buildout
+  $ 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
@@ -93 +170 @@
   $ bin/kofactl stop    # stop running instance (also 'restart' possible)
 
-When Kofa is running, you can access the portal on port 8080:
+That should start you.
 
-http://localhost:8080/
-
-Enter the credentials (username 'grok', password 'grok' by default)
-and name and add a `University`.
-
-Congratulations, you got Kofa running.
+Have fun with Kofa!
 
 
 
-.. _Debian: http://www.debian.org/
+.. _Debian: https://www.debian.org/
+.. _docker: https://
 .. _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/
+.. _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: http://www.zope.org/
-.. _zc.buildout: http://cheeseshop.python.org/pypi/zc.buildout
+.. _Zope: https://www.zope.org/
+.. _zc.buildout: https://pypi.org/project/zc.buildout