Docker Apps/Package Based

As stated in App_Center/Dev/Docker_Apps#Two_kinds_of_Docker_Apps there are two types of Docker Apps: Apps that base upon a stand-alone Docker image and Apps that install packages in a UCS based container (called ucs-appbox).

This chapter covers Apps that base upon Debian packages.

Use case

A Docker App that is based upon packages is easy to create if you already have Debian packages at hand. The image for these Docker Apps is (normally) a UCS based image. Thus, such a Docker App is good for deep integration as in the container itself runs, e.g., a Univention Directory Listener.

Life cycle

The life cycle of a package based Docker App is basically the same as that of an image based Docker App (see Docker_Apps/Image_Based#Life_cycle). All points are valid here, too. Yet, there is one important additional feature of package based Docker Apps: Images do not necessarily have to be exchanged when a new App version is released (compare to Docker_Apps/Image_Based#Upgrading_an_image_based_Docker_App).

Important

Because of the way Docker Apps are uninstalled, no package uninstallation is taking place! The packages are not uninstalled, the container is removed. This means that no postrm Debian helper scripts are run. If you need that logic, you need to put it into the uinst scripts (see Docker Apps/Container Scripts).

The Docker Container of a package based Docker App is more a virtual mashine that may actually run for as long as the Docker Host runs. App updates may be installed by installing new versions of the packages. There is no need to stop the container, remove it and set up a new one. It is more of a apt-get dist-upgrade.

Technically, when installing the App, a repository is included in the then started ucs-appbox container. From there packages as specified in the ini file are installed via APT.

Important

Installation is unattended. You cannot interactively ask the user (e.g. for some kind of initial "root" password).

When upgrading the App, the old repository is removed and a new repository is added and the packages get updated. This is all done automatically by the App Center (more specifically: by scripts that live in the container and are called by the App Center).

That being said, an exchange of the image is allowed (just change DockerImage and do not include the old image in DockerAllowedImages). In this case, the section from the image based Docker Apps applies.

Docker Apps: Files

An App may ship additional files along with the ini file. These are not scripts as in the previous section, just plain text files.

env

An environment file used during the creation of the Docker Container. It contains static configuration options passed to the container via docker create ... --env ${env}. See the Docker Documentation.

univention-config-registry-variables

This file contains (a superset of) UCR variable definitions. These definitions exist on a regular UCS to describe the specific variables in the UCR database. In this context, they are used to set UCR variables in the Docker Container. If this file is present, there will be a form before the installation of the App and after the installation on a separate page within the App Center module ("App Settings"). Further information can be found in Section 8.2.

schema

A schema extension for LDAP. This is useful if you want to, e.g., extend the user objects of UCS by an attribute like "This user may use the App" (see Section 8.3). The file will be copied to /usr/share/univention-appcenter/apps/APPID/APPID.schema during installation. See the LDAP documentation for the syntax of a schema file. If you need an "official" OID namespace, Univention can provide one. It is important to note that shipping this file alone is not enough. You need to register it in the join script (see Section Docker Apps/Container Scripts) via ucs_registerLDAPExtension "$@" --schema "/usr/share/univention-appcenter/apps/$APP/$APP.schema".

Docker Apps: Directories

TBD; /var/lib/univention-appcenter/...

Example

As stated above, a package based Docker App is much like a virtual mashine. You develop Debian packages for a minimal member server. The App Center takes care of the containerization.

In this section, we will develop a Docker App based on the package dudle. Dudle is a clone of Doodle to organize polls and the like.

Actually, this section is rather short. Apart from the packages there is not very much to do with package based Docker Apps. The App Center does most of the work. And as the underlying image is a UCS, the interesting parts work out of the box.

The following ini file will be used:

[Application]
ID=dudle
Logo=dudle_logo.svg
Code=DU
Name=Dudle
Version=1.1.0-1
License=free
NotifyVendor=True
Description=Schedule events and execute polls very easy
LongDescription=Dudle is a clone of the well-known solution Doodle and allows to comfortably find joint appointments with multiple participants or carry out polls very easy. It radically simplifies the process.
Thumbnails=dudle-screenshot.png
Categories=Collaboration, Education
Contact=feedback@univention.de
NotificationEmail=appcenter-reporting@univention.de
Maintainer=Univention GmbH
WebsiteMaintainer=http://www.univention.com/
WebInterface=/dudle
WebInterfaceName=Dudle - Appointments & Polls
SupportURL=https://www.univention.com/products/support/community-support/
DefaultPackages=dudle
DockerImage=docker.software-univention.de/ucs-appbox-amd64:4.1-0
DockerScriptSetup=/tmp/setup

[de]
Description=Terminfindung und Abstimmungen einfach durchführen
LongDescription=Dudle ist ein Klon der bekannten Lösung Doodle und dient wie diese dazu, einfach und bequem gemeinsame Termine unter mehreren Teilnehmern zu
finden oder einfach Abstimmungen vorzunehmen. Sie verkürzt so den Abstimmungsprozess erheblich.
WebInterfaceName=Dudle - Termine & Umfragen
WebsiteMaintainer=http://www.univention.de/
SupportURL=https://www.univention.de/produkte/support/community-support/

Notable variables:

DefaultPackages

The package dudle has been built and uploaded to the App Center server: http://appcenter-test.software-univention.de/univention-repository/4.1/maintained/component/dudle_20160201/.

DockerScriptSetup

A custom setup script will be shipped and copied to this location. The script can be found here. Dudle is a very simple App. Linking /var/www/ in the container to the data directory will save all relevant files in the shared volume. Note that it executes the original setup script at the end.

That's about it. The crucial part (other than developing the software, of course) is saving the user data somehow in the shared volume. This is important when the container is removed. This happens during an image upgrade (which is actually not very common for UCS based images, as they can update themselves) and during an uninstallation. In the latter case, the shared volume helps to start where it ended after the user reinstalls the App.

In this section, this is done by linking the data directory to the shared volume. For more complicated szenarios, there are store_data and restore_data_after_setup, see Docker Apps/Container Scripts. If the data (partially) is in a database, see also Integration with UCS/Database.