Docker Apps/Package Based

From Univention Wiki

Jump to: navigation, search


As stated in 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.

What to do in a nutshell

To actually add such an App to Univention App Center, you need to:

  • Create an ini file
  • Thereby choose the Docker image. Should probably be the latest appbox image:
    DockerImage=docker.software-univention.de/ucs-appbox-amd64:4.1-4
  • Have a logo file (better 2) in SVG
  • Build debian packages of your software
  • Write a join script / unjoin script (maybe minimal, only "Best practices")
  • Optional: Further integration, e.g., web interface or settings
  • Optional, encouraged: Write README files

Most of these things can be done using the Provider_Portal/Apps (which creates an ini file, lets you upload logos, write README files). The portal also can be controlled remotely, which makes integration in your build chain possible.

Important
Each App gets its own repository on appcenter.software-univention.de. Although it requires knowledge of App Center internals, you should consider your software packages to be public by the time publishing the App in Univention App Center.

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 machine 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.

Example

As stated above, a package based Docker App is much like a virtual mashine. You develop Debian packages for a minimal UCS 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-4
DockerScriptSetup=/tmp/setup
RequiredUCSVersion=4.1-3 errata293

[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.
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 scenarios, 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.

Personal tools