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
:
- The first line of our Dockerfile,
FROM ubuntu
pulls down the image f49eec89601e - 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. - 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 (
--rm
flag). 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.