Difference between revisions of "Migration to Docker"

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]]
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 <tt>DockerVolumes</tt> 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).

Latest revision as of 15:05, 27 August 2018

Personal tools