Migration to Docker

This page briefly describes what is to be done when migrating Non-Docker Apps to Docker Apps/Package Based.

Technical approach

When the App Center detects an update from one App version to another and the latest version uses Docker whereas the installed one did not, the App Center runs a special mechanism:

First the container is started and configured. If this succeeds, the old App (the packages on the Docker Host) are removed (not purged...). Keep that in mind when migrating. The packages may delete certain files when removed, leaving the new App version broken.

The join script of the new App version is run a second time in case it was removed from status file by the uninstallation process of the previously installed App version. So one may fix things there.

ini file

The most important change is setting a Docker Image to docker.software-univention.de/ucs-appbox-amd64:4.3-0.

Parallel versions

When the new, dockerized version is released, users of the old version will not see an update by default. The new Docker version will only be installable by new users that never had your App installed before. This is to prevent migration errors in an automated process. Instead you now have two "main lines" of your App, the Docker version and the Non-Docker version. You could then put a document somewhere explaining how to migrate every bit step-by-step.

Note

Technically, the upgrade to the new Docker version is prohibited by an UCR variable. The document describing what to do to migrate to the Docker version should start with "ucr unset appcenter/prudence/docker/myapp".

You can support both lines, the Docker and the Non-Docker one, for a while.

Packages

Packages may not need to change, especially the "vanilla" App packages. The additional features of Docker Apps may make a dedicated integration package unneeded. Schema extensions (see Docker Apps/Files) and the (un)join script may live unpackaged next to other meta files (see Integration_with_UCS/Join). This was actually one goal of the Docker integration of Univention App Center: App Providers may tailor their container as needed, while most of the integration work can be done from "outside".

Note

Scripts like "setup" (see Docker Apps/Container Scripts) may be overridden and the join script may do a lot of configuration work. But at some point things get complicated and it may be better to structure business logic in a dedicated package. There is nothing wrong with installing a "univention-myapp" integration package inside the container.

If you plan to use the Host database server (see below) you might want to remove mysql-server or postgresql from your dependency chain.

Database

See Integration with UCS/Database for how to make use of the Docker Host's database management systems. For the migration, adjust the ini variables to the values of the last non-docker version. In this case, no data migration needs to be done.

Keep in mind that if you are using the the Host's services, every usage of "mysql" or "psql" in your packages' postinst scripts need to be adjusted to not go against localhost, but against the Docker Host (which is "$DB_HOST" or whatever you configured).

Data migration

You can copy some data from the old App version to a volume that is mounted in both, the Docker Host and Container and then use this data while setting up the App inside the container.

See Docker Apps/Container Scripts: You may copy files in the preinst file and overwrite restore_data_before_setup or restore_data_after_setup. Keep in mind that copying may be expensive. It may be better to specify volumes for certain directories that will then be present on the Docker Host and in the Docker container.

Access

Tasks that could be accomplished by a CLI tool now need to be executed inside the container:

univention-app shell myapp /usr/bin/myapp-cli --do-something

Likewise, files can be accessed only in the container:

univention-app shell cat /var/log/myapp.log

This may be important for your support team.

Note

It may be possible to mount certain files from the container to the host transparently using DockerVolumes in the ini file. It may be confusing if you do not manage to mount them all but only a small portion, though (e.g., only log files, but not the configuration files).