App Settings

From Univention Wiki

Jump to: navigation, search

Apps may be configured from within the App Center. A file describing App Settings may ship with the App, rendering a form for the user.

App Settings

There are a variety of possible Settings that can be defined. The file is in the ini file format. Easy example:

Type = String
Description = A string type
Description[de] = Eine Zeichenkette
InitialValue = The "default" value of this setting; optional

This will render a form:

The settings page opens in the App Center module when the App is installed

A simple input field

After applying this form, the variable "myapp/mysetting" will be saved inside the container of the Docker App. The App can then react on this change.

Where are the Settings stored?

For Docker Apps, they are stored inside the container in the Univention Config Registry (UCR). If you use a Docker App based on UCS with debian packages, you can easily access this variable using UCR as a CLI tool or by importing the python library. As UCS is the basis, you also get UCR templates, etc., for free.

For Docker Apps that are based on their own image, a "UCR like interface" is used, meaning that the settings are stored in a file:

univention-app shell myapp cat /etc/univention/base.conf | grep mysetting
myapp/mysetting: The "default" value of this setting; optional

So you can still use the variable, just not as comfortable.

Even Non-Docker Apps are supported. The variables are stored in UCR as well, but on the server itself.

How do I react on Setting changes

After the Settings are applied, two scripts are called. First, the script configure_host is called. It runs on the Docker Host and therefore also has access to the container (using "univention-app shell"). After that the script configure is called. It may be sufficient for many applications to just have this easier script that runs directly inside the container. How you actually make the variables known to your application is up to you.

Configure script

This is one script that App Providers may ship along with their App. See Docker_Apps/Container_Scripts; it counts as an "inner script". The file name extension is .configure.

It can be activated by hand:

univention-app configure myapp

But it is also called when the Settings are used, i.e., applied.

The Settings have been stored prior to calling the script! The script is not called with the values. Instead, it is assumed that the script handles reading the values where needed.

The script will instead be called with this signature:

/path/to/configure <action> --app myapp --app-version 1.0 --error-file /tmp/XXX

where <action> is one of ('settings', 'install', 'upgrade', 'remove'), depending on when the App is configured. See also ???

Configure host script

This is one script that App Providers may ship along with their App. See Docker_Apps/Container_Scripts; it counts as an "outer script".

Everything said in #Configure script also holds. But this script is actually called before the inner configure script.

Thus you can do things on the Docker Host before you configure the Docker Container. If you instead would need to configure the Container before the Host, you have access to it by just using

univention-app shell myapp ...
Personal tools