Troubleshooting the Docker build process

When working with Docker and building Docker images, you will likely run into issues where your images fail to build. While this can be difficult to navigate, a basic understanding of how Docker builds images will set you on the path to success.

The first thing to understand is how Docker builds an image. Take a look at the snippet of my example Dockerfile below:

FROM ubuntu 
ENV DEBIAN_FRONTEND noninteractive
# Install base packages
RUN apt-get updater # I know this is a problem, more below!
RUN apt-get install -y python-software-properties software-properties-common
...

When you run docker build, each command in the Dockerfile (e.g. FROM, ENV, RUN) is a step in the build process. Docker processes each step in an intermediate container. Those intermediate containers can succeed or fail. If they succeed, the intermediate container is merged with the image from the last successful build step, and then the intermediate container is deleted.

From the Docker Docs: Docker images have intermediate layers that increase reusability, decrease disk usage, and speed up docker build by allowing each step to be cached

Let’s look at what happens when we run docker build:

Error seen running docker build

1. The first line of our Dockerfile, FROM ubuntu pulls down the image f49eec89601e
2. The second line, ENV DEBIAN_FRONTEND noninteractive is run in intermediate container e2556795c830. If this is successful, as we see above, it will save a new image, bf6d2fd8e919, and then remove intermediate container e2556795c830.
3. The third line, RUN apt-get updater is run in intermediate container cfcbc0de8f7b. This is where our command is failing.

The error we see is in step 3, but the intermediate container is not available. You can verify this with docker ps -a to view all containers, both running and stopped.

Step 2 completed successfully and so we have an image with the id bf6d2fd8e919 that we can run to troubleshoot the failing third step. We would do this with docker run:

docker run --rm -it bf6d2fd8e919 bash

This command will:

• Run the specified Docker image — bf6d2fd8e919.
• Keep STDIN open even if not attached (-i flag).
• Allocate a pseudo-tty (-t flag).
• Automatically clean up the container and remove the file system when the container exits (--rmflag). This is optional.
• Run the bash command inside of the container.

For more information on docker run and its options, see here.

Once inside the container, you can run the command that is failing and troubleshoot any issues you are seeing. In my case, I would enter apt-get updater, get an error message, and realize I should be using apt-get update instead.

Continue with this process until your image builds successfully. Let me know in the comments below if you have any tips or tricks for troubleshooting your Docker builds.