# Guide: docker compose // :toc: // Set toclevels to be at least your hugo [markup.tableOfContents.endLevel] config key :toclevels: 4 == Docker Compose In this scenario, we have to maintain a docker-compose file and we want to be sure that we always use the latest available docker. === Requirement . Updatecli . IDE . A GitHub Personal Access Token ==== Updatecli Binary {{< updatecli_description >}} ==== IDE {{< ide_jsonschema >}} ==== GitHub Personal Access Token As we are going to interact with resources on Github such as github repository and GitHub packages, we need a personal access token. More information on the GitHub documentation link:https://docs.github.com/en/authentication/keeping-your-account-and-data-secure/creating-a-personal-access-token[creating-a-personal-access-token] === Description Docker image versions are identified using two methods, either the docker image tag or the docker image digest. *Tag* A docker image tag is useful when we want to have an easy to identify human-readable version like in `nginx:1.17` where `1.17` is the tag. Unfortunately, a docker image tag can be easily overridden, whether on purpose or not. As when using the tag `latest`. This means that a docker image tag can't be considered as a source of truth. *Digest* The second method to identify a docker image version is by using its digest like in `nginx@sha256:8269a7352a7dad1f8b3dc83284f195bac72027dd50279422d363d49311ab7d9b` where the string following `nginx@sha256:` is the digest. A digest is a hash referencing a specific version of a docker image tag, in this case, `nginx:1.17`. A digest is immutable, we can always rollback to a specific digest if needed. However, it's not convenient to identify which version we're referencing without a little further investigation. The problem could be summarized as, "do we want to only use a well-defined docker image by using digests but with the cost of losing readability?" or, "are we accepting the risk of running an unwanted version by using image tags?" It depends on how important we value readability versus uniqueness, but a useful rule of thumb is to consider the docker image build strategy. What's the risk of running an unwanted version and how big is the chance of having to rollback. If we only build one image by version and that version is regularly updated then preferring readability by using docker image tag seems reasonable otherwise in any other scenarios it's usually safer to use docker image digest. Now that we know what to update and why, let see how to do it using updatecli. === Docker Image Tag When we want to automate image tag updates, we have to identify the process used to define those tags, and if that process is automated. Then you can more than likely also automate the version update and this is where updatecli can play a role. Using `updatecli`, you specify this process in the source stage, then if needed you check a condition and if the condition is satisfied then you update the version in your target file. Considering again, the example of regularly updating the Jenkins version. We know that a release is published every week on a maven repository, then a docker image build is published on DockerHub. Considering the build strategy, it would seem to be fine to use a docker image tag. Let's consider this docker compose file, which the three examples below all share: .docker-compose.yaml [source,yaml] ---- {{< include "assets/code_example/docs/guides/docker-compose/docker-compose.yaml" >}} ---- Now we write an updatecli configuration with a source, conditions, and one target .updatecli.1.yaml [source,yaml] ---- {{< include "assets/code_example/docs/guides/docker-compose/updatecli.1.yaml" >}} ---- `updatecli pipeline diff --config updatecli.1.yaml` Updatecli queries the maven repository 'releases' located on `repo.jenkins-ci.org`, to determine the latest version. If it finds one, a source transformer appends the suffix `-jdk11`, as we are looking specifically for the java 11 version, and a target transformer prepends the prefix `jenkins/jenkins:` to build the full image reference. We validate that the docker image exists on DockerHub and then we test that the value in the file 'docker-compose.yaml' for the key `services.jenkins.image` is correct. If not then we bump it. If happy with the changes then we apply them by using `apply` instead of `diff`. `updatecli pipeline apply --config ./updatecli.1.yaml` === Docker Image Digest As explained earlier, sometimes it's preferable to use the docker image digest, if we need to rely on a specific version, or if we want to easily rollback. Most of the configuration remains the same as the previous example. This time the source is of kind `dockerdigest` and we don't test if an image exists on DockerHub as we're already asking DockerHub for the latest image. We start from the same `docker-compose.yaml` shown above. .updatecli.2.yaml [source,yaml] ---- {{< include "assets/code_example/docs/guides/docker-compose/updatecli.2.yaml" >}} ---- This time updatecli queries DockerHub to retrieve the digest for the docker image `jenkins/jenkins:lts-jdk11`. If it finds one, then we test that the value in the file 'docker-compose.yaml' for the key `services.jenkins.image` is correct, otherwise we change it. Again, if the changes are acceptable then we apply them by using `apply` instead of `diff`. * `updatecli pipeline diff --config updatecli.2.yaml` * `updatecli pipeline apply --config updatecli.2.yaml` === Git/GitHub Now that we have an easy way to update docker image versions, we are missing a way to save, review, and rollback those changes. For this, git is an excellent tool. Either we directly commit and push to a git repository, or we use the GitHub workflow by pushing to a temporary branch. If using GitHub we can also submit our changes via a pull request. We keep the same `docker-compose.yaml` as before, and extend the manifest. While the configuration remains similar to the earlier example, this time two new elements are introduced. We can define generic values in the file or read values from an environment variable like `{{ requiredEnv "UPDATECLI_GITHUB_TOKEN" }}`. The `scms` block defines the github repository configuration, and the `actions` block turns the pushed branch into a pull request. .updatecli.3.yaml [source,yaml] ---- {{< include "assets/code_example/docs/guides/docker-compose/updatecli.3.yaml" >}} ---- And now you can use the same commands as before, with the credentials the manifest expects: [source,shell] ---- export UPDATECLI_GITHUB_TOKEN= export UPDATECLI_GITHUB_ACTOR= updatecli pipeline diff --config updatecli.3.yaml updatecli pipeline apply --config updatecli.3.yaml ---- === Conclusion With this scenario, we saw how to automatically update a docker-compose file using custom strategies with updatecli. Updatecli is a small single binary that is suitable for use in your favorite CI environment.