Difference between revisions of "Docker Apps/Package Based"

From Univention Wiki

Jump to: navigation, search
(Link to new documentation)
Line 1: Line 1:
[[Category:App Center Developer Guide]]
#REDIRECT [[App Center Developer Guide]]
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 [[Meta files/ini|ini file]]
* Thereby choose the Docker image. Should probably be the latest appbox image: <pre>DockerImage=docker.software-univention.de/ucs-appbox-amd64:4.1-4</pre>
* Have a [[Meta files|logo file]] (better 2) in SVG
* Build debian packages of your software
* Write a [[Integration with UCS/Join|join script / unjoin script]] (maybe minimal, only "Best practices")
* Optional: Further integration, e.g., [[Integration with UCS/Web interface|web interface]] or [[Integration with UCS/Settings|settings]]
* Optional, encouraged: Write [[Meta files|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:
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.
Categories=Collaboration, Education
Maintainer=Univention GmbH
WebInterfaceName=Dudle - Appointments & Polls
RequiredUCSVersion=4.1-3 errata293
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
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 [http://appcenter-test.software-univention.de/univention-repository/4.1/maintained/component/dudle_20160201/setup 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]].

Latest revision as of 15:11, 27 August 2018

Personal tools