Docker Apps/Container Scripts

For every Docker App, the App Center server may hold several scripts that do not need to be packaged. Even for package based Docker Apps, it is possible to integrate it without needing to build an additional integration package (like univention-app.deb). That being said, with increasing complexity, it is advised to build such a package nonetheless. Furthermore, not everything can be achieved easily with these scripts. There are interfaces rarely used that the App Center does not support. Should your Docker App require these interfaces, it may be necessary to create a package to (also) ship the scripts mentioned below.

We need to distinguish between outer scripts and inner scripts. An outer script is called on the Docker Host, inner scripts are called inside the running Docker Container.

All scripts are called with root privileges. For inner scripts this means the local root of the Docker Container. Some scripts may get LDAP credentials. Normally, these credentials are those of the Administrator account.

Important

The following list assumes that a package based Docker App is used as it is more important for these to have the scripts. Anyway, all of these scripts may also be used in image based Docker Apps. Normally, image based Docker Apps do not ship these scripts in the container itself. In this case, it is possible to upload them to the App Center server along with other meta files. They will be downloaded by the App Center and copied into the container right before execution. Package based Docker Apps already have these scripts in place. But even these Apps may upload scripts to the App Center server. These files will also be downloaded and copied, thus giving you the option to further enhance the functionality provided by default. It is strongly advised to not overwrite the existing scripts (which is possible), but instead copy them to another place and call the original script as the default behaviour is very likely important. See also the #Examples

Installation / uninstallation

The following scripts are for installation and uninstallation. Upgrades use these scripts, too, if (and only if) the upgrade includes an image exchange (i.e. the new version with the new ini file specifies a different DockerImage). In that case the old App is uninstalled and the new App is installed.

Note

These scripts may also be useful for image based Docker Apps. Especially inst, uinst, store_data, restore_data_after_setup.

preinst

An outer script called before the Docker Container is initialized, even before the image is downloaded. Its purpose is to check whether installation may be successful. For example, the preinst may fail if certain hardware requirements are not met. Any exit code other than 0 will result in cancellation of the installation process. If the installation of an App is the result of an image exchange (and thus more of an upgrade) the preinst is also called. This script may also be used to setup the Host environment for the App before container creation, e.g., creating an outer directory with proper permissions.

restore_data_before_setup

An inner script called before setup is called, right after the container is started. Its purpose is to restore those bits that may be needed to successfully run the setup script. May be useful in an upgrade process where one needs to restore the state the old container was in instead of setting up the container as if it were fresh.

setup

An inner script and heart of the whole installation process. By default it joins the system, (a script called univention-join provided by Univention), adds the repository that was created on the App Center server and installs DefaultPackages specified in the ini file. After that it once again joins, running all scripts that may have been installed during the App installation. If the script fails (exit code != 0) the installation is aborted.

restore_data_after_setup

An inner script called after setup is called. Its purpose is to actually restore the data that may have been saved in store_data – now that the App is up and running but the database is still empty.

inst

Also called join script. An outer script called after the Docker Container is configured. Think of it as a postinst of the App. See our page about Join scripts or the Developer Reference for how to write a join script. If the join script runs successfully, the join script may save this information in a status file. If this does not happen, the user is constantly reminded to re-run the join script. So the join script does not need to run successfully. The installation will not be aborted at this point. But of course at some point it should run through successfully. The main purpose of the join script is to set up the domain for the new App, e.g. by adding a domain user that can be used as the LDAP binddn that your App may need to authenticate against the central user management of UCS.

prerm

An outer script called before the Docker Container is removed. Its purpose is to check whether an uninstallation may be successful. But it may be used to somehow prepare the system for the uninstallation. For example, the prerm may fail if other software still depends on it. Any exit code other than 0 will result in cancellation of the uninstallation process.

store_data

An inner script called before removing the Docker Container. In fact the App is not really uninstalled. The container is just thrown away. This also happens during image upgrades: The current image is thrown away and a new image is set up. Therefore it is important to store the data of the current App to be able to start into exactly that state when the container was removed. You may call any App specific commands like myapp-backup --full or just copy the important files. The App Center always mounts the following directory into the container, which can be used to store the data (and later restore the data from there as the very same directory will be mounted into the new container): /var/lib/univention-appcenter/apps/$APPID/data/.

uinst

Also called unjoin script. An outer script called after the Docker Container is removed. Think of it as a postrm of the App. See the Developer Reference for how to write an unjoin script. It should somehow revert most (if not all) changes done in the inst script (or join script). With the notable exception of schema registration. An LDAP schema extension should never be removed once it was registered.

Upgrade within the container

The following scripts are for upgrading the software within the Docker Container. Three possible scenarios have to be covered:

• Upgrade of system packages (security fixes, UCS calls them Errata Updates)
• Upgrade of the operating system (a new patchlevel release or even a minor/major update of UCS (4.1-1 or 4.2-0))
• Upgrade of App packages, i.e. a new version (with the same DockerImage) was released

Note

These scripts are useful for a Docker Container to run indefinitely and never be replaced. As such, they are probably not important to image based Docker Apps.

update_available

An inner script called when the App Center wants to find out whether the container may install package updates or release updates. By default, this is done automatically once a day. It can be triggered manually, too, though. The script needs to echo the result: packages if mere package updates are available. These include security fixes for operating system packages. release: RELEASE if a new version of the operating itself is available. RELEASE can be anything, it is just presented to the user. Note that the script does not search for App updates, nor does it search for a change in the DockerImage! This is done by the "outer" App Center.

update_packages

An inner script called when (all) updates of existing packages shall be installed.

update_release

An inner script called when a new version of the operating system shall be installed.

update_app_version

An inner script called when a new version of the App packages shall be installed. This script is different from update_packages. This has technical reasons, because for normal UCS based Docker images, this requires a new repository to be registered. But it also has usability reasons: First, users may want to distinguish between necessary, stability improving package updates and (potentially) ground-shaking App updates; second, at least the UCS containers are configured to install security / stability updates automatically.

While the container is running

The following scripts are run when Settings are applied during runtime. Depending on the Settings, the scripts may also run after the installation / upgrade or before the removal of the App. See Settings.

configure

An inner script with one additional positional argument. The first argument is either "install", "upgrade", "remove", "settings", depending on when the Settings were shown and applied.

configure_host

An outer script that actually runs before configure. In case the host has to change something on his side depending on the Settings, this can be done here.

Examples

setup in UCS based containers

A setup in a Package based Docker App that temporarily enables the unmaintained repository of UCS. Put DockerScriptSetup=/tmp/setup into your ini file - otherwise /usr/share/univention-docker-container-mode/setup is overwritten and will the script will call itself.

#!/bin/bash

set -e

# some helper functions, especially "die"
. /usr/share/univention-docker-container-mode/lib.sh

ucr set repository/online/unmaintained=yes
univention-install --assume-yes python-pip || die "Setup failed"
pip install requests
ucr set repository/online/unmaintained=no

# call the original script! Otherwise the normal package installation will not work
/usr/share/univention-docker-container-mode/setup "$@" || die "Setup failed"

setup in "ordinary" docker containers

A setup script that could be run in the standard container that the project ships to everyone, but enables UCS specific integration. Put DockerScriptSetup=/tmp/setup into your ini file - or any other path.

#!/bin/bash

set -e

gem install net-ldap --no-doc
# do some configuration stuff; see https://wiki.univention.de/index.php/Integration_with_UCS/LDAP