# Docker Compose

Documentation on how the LOFAR station control software utilizes docker-compose.
This documentation is intended for developers listing strategies and their
respective advantages and disadvantages. In addition, this documentation
contains developer expectations that they should uphold to.

## Image tagging and change detection

Preventing unnecessary builds of docker images reduces build times and increases
iteration speed. In order to achieve this the project requires properly tagged
images and mechanisms for change detection.

For change detection the system relies on git. Git is used to determine the
directories and files that have changes between the current and previous commit.
All image related change detection mechanisms are based on this difference.

Using docker cache within the dind service is impractical see:
https://gitlab.com/gitlab-org/gitlab-foss/-/issues/17861

### Types of containers and specific strategies.

- Devices
- Simulators
- Base images
- Services

Devices, are currently bound to the host upon building due to the intrinsics of
how environment variables are used. They will have to be rebuild and can not be
pulled from a local registry.

Simulators, Since the source code for simulators is maintained by other teams
we can not accurately determine from our repository if the simulator has
changed. Instead, the images should be build by the teams their respective CI
pipelines. We would simply pull these images as base images.

Base images, these are detected by changes to the .env file in the
docker-compose directory. When changed they will be downloaded from the remote
registry and uploaded to our own using matching tags.

Services, these are detected by changes to the .yml file or directory of the
respective service inside the docker-compose directory.

### Setup and maintenance

All behavioral logic to orchestrate change detection and image pushing can be
found in the sbin/tag_and_push_docker_images.sh script as well as the
.gitlab-ci.yml. The shell script relies on the fact that each .yml file in the
docker-compose directory corresponds to one image.

### Gitlab CI phases

Docker images are build and pushed in two stages. First external images are
downloaded, retagged and pushed to our own registry.

`git diff --name-only HEAD~1..HEAD ./`