Best practices for adding customizations to images

Follow these best practices when adding customizations to images.

Always specify the package version to install when creating a custom image.

If you don't specify packages versions, pip will always install the most recent packages in its repository, which can lead to problems when you re-build the custom image after new versions were published to the repositories.

When you specify package versions, you might still run into problems if those packages pull in dependencies. To avoid this kind of problem do the following:
  1. Run an image build that installs the packages that you require.
  2. From the build log output, collect a list of all packages and versions that were installed.
  3. Add comments to the install commands without package versions. These comments will be useful when packages need to be updated.
  4. Add new install commands with the full list of packages and their versions.
  5. Rebuild the image.

When you change the install-as-user.sh script, the next image build on your development machine will rerun all the commands in the script. When you change the install-as-root.sh script, the next image build will rerun the commands in that script, all subsequent commands in the Dockerfile, and thereby all commands in install-as-user.sh. This might cause tedious delays while developing a custom image with multiple customization steps.

To leverage image layer caching using Podman or Docker, do the following:
  1. Add the root customizations before the user customizations.
  2. Create an extra work-in-progress.sh script and duplicate the COPY/RUN commands in the respective section of the Dockerfile to execute it. Only add the commands for the specific customization steps that you are working on to the work-in-progress.sh script, so that only these steps are rerun for every build attempt.
  3. After you have verified that the new customization step works, move the commands into the respective install-as-*.sh script and proceed with the next customization step.
  4. When you're done, remove or comment out the COPY/RUN commands for running work-in-progress.sh.