Docker image build

[]

The final (customized) application is deployed to a productive environment as a Docker container, created from a Docker image. This Docker image must be built by the Dockerfile. This builds both backend and frontend code, adds libraries and static files, and saves the result as single Docker image.

Requirements

Installed Docker. If you also did the development, you should already have it.
It is recommended to do the build on a CI/CD (Continuous Integration / Continuous Delivery) server, but it is also possible to run the build process manually on any developer machine.

Steps to build an image for deployment

Prepare a clean repository

Please make sure that the build is done with a clean repository without any extra files - even ignored ones! Some of them might break the build in strange ways. I.e., you need a fresh workspace, created with git clone or at least with git clean -fdx.

Run build process

Also, please read the next section to familiarize yourself with any possible issues.

BASH

# in the main (root) directory of this repository
docker build -t hcms-client:latest -f deployment/docker/Dockerfile .

When preparing for real deployment, the resulting image needs to be tagged by a correct name (the one that contains the correct repository) and pushed. For example:

BASH

docker build -t hcms-client:latest -f deployment/docker/Dockerfile .
docker tag hcms-client:latest  960443856523.dkr.ecr.eu-central-1.amazonaws.com/hcms-client:latest
docker push 960443856523.dkr.ecr.eu-central-1.amazonaws.com/hcms-client:latest

Alternatively, it is possible to use the final image name as the -t argument directly in the docker build command and skip the docker tag part.

Known `docker build` issue

The docker build command has (depending on the version) a known bug that could result in an invalid build.

Expected result

The new image contains your changes (i.e., changes in the source files).

Actual result

You run the newly built image as a container, but the result looks like a clean application you have started with. A detailed investigation of the generated JavaScript files (via docker run --rm -it --entrypoint=/bin/ls <image> -l web/) shows old timestamps. However, the timestamps should match with the time you ran the docker build command to build this image.

Cause

Based on our observations, building the image in a repository that contains any extra (even git-ignored files) seems to increase the chance of this bug happening. Apparently, docker build uses some kind of internal cache; the real cause of this bug is not yet known and is in the hands of the third-party provider.

Workaround

You need to run docker builder prune --all to clean all the cache before building the image. Please keep in mind that adding an option --no-cache to docker build does not suffice, since it is a completely different kind of cache. It might be, however, used in the docker builder prune command.

Influence on CI builds

Normally this know issue is not a problem, because the build runs inside a temporary Docker container and thus cannot leave any file behind.

However, some CI systems (for example "gitlab ci" in combination with "kaniko") offer a special feature to pass files from one build to another. In our case, this additional files will break the build. Please make sure no such feature is ever enabled!