Painless Docker - 2nd Edition

Optimizing Docker Builds: The Base Image

The base image is the foundation of everything that follows in your Dockerfile. It decides what operating system userland you get, what package manager exists (if any), what libraries your application links against, how big the final image will be, how fast builds run, how easy debugging will be, and how painful security patching becomes. In other words, the base image choice is not cosmetic but a fundamental architectural decision.

Before moving to advanced recommendations, let's cover some basic best practices regarding base images:

• Choose official images when possible: Official images are maintained by the Docker community or the software vendor and are generally more secure and reliable.
• Use specific tags: Instead of using the latest tag, specify a particular version (e.g., python:3.14-slim) to ensure consistency across builds. If you use tags like latest, the base image can change without you noticing. As a result, the Docker cache is invalidated from the first layer, and everything rebuilds.

When it comes to optimizing Docker builds, size is often a key consideration as it directly impacts:

• How long it takes to pull images in CI and production
• How much disk is consumed on hosts and registries
• How fast your local development environment can start containers

In production environments, other factors related to orchestration and networking also come into play:

• How much bandwidth you burn across clusters and regions
• How quickly nodes can scale up during deployments
• How fast rolling updates and rollbacks can occur
• And more.

A container image is not a virtual machine. It doesn't ship a kernel. It ships user-space files: binaries, shared libraries, certificates, language runtimes, and sometimes a minimal shell and package manager. When you choose ubuntu, you are choosing a large and flexible userland. When you choose alpine, you are choosing a tiny userland with a different C library. When you choose a "distroless" image, you are choosing almost no userland at all, just enough to run the app.

Smaller images are generally better for development and production; for example, our Python application uses the -slim variant of the official Python image, which is smaller than the full version. However, here is the catch: Smaller images are not always faster to build. If you pick a minimal base image that lacks build tooling, you may spend more time installing compilers and headers during the build. That is where multi-stage builds become valuable.

BusyBox, for example, is an extremely small base image (about 2.1MB), but it lacks package managers and build tools. It can be a good choice for embedded systems and environments where size is critical, but it may not be suitable for applications that require a more complete userland.

Alpine Linux is another popular minimal base image (about 5MB) that builds on top of BusyBox but includes the apk package manager. A package manager makes life easier when you need to install dependencies during the build process. Instead of compiling everything from source (time-consuming), you can use apk to install pre-compiled binaries quickly. However, Alpine uses the musl C library.

One of the biggest compatibility traps is the C standard library. Most mainstream Linux distributions use glibc (GNU C Library) as the standard C library, which is widely supported and compatible with a vast array of software.

Alpine uses musl, which is smaller and simpler than glibc but has some compatibility issues with software that expects glibc. In our example, many Python packages publish prebuilt wheels targeting glibc-based distros. On Alpine, those wheels might not work, so pip falls back to building from source. That can turn a quick install into a long compile step, and it can introduce build failures if you are missing system dependencies. In this very specific case, using a slightly larger base image that includes glibc (like python:3.14-slim instead of python:3.14-alpine) can lead to faster builds and fewer headaches. We are always using our Python example to illustrate this point, but the same applies to other languages and runtimes.

Minimal runtime images are great until something breaks at 3 a.m.! If your image has no shell, no curl, no ps, and no package manager, debugging inside the container is harder. This doesn't mean you should ship bloated images. It means you should plan your debugging strategy. You can, for example:

• Use a slim or distroless runtime image for production.
• Use a separate debug image, or attach ephemeral debug containers in orchestrators.
• Keep tooling out of production images unless you truly need it.
• Use multi-stage builds to keep build tools out of the final image.

Small images are a great choice, but they should not come at the cost of developer productivity and operational reliability. Choosing a balanced base image could be a reasonable compromise. There's no rule that fits all scenarios, so evaluate your specific needs and constraints before deciding.

Here are some common choices for base images:

BusyBox

BusyBox runs in various POSIX environments such as Linux, Android, and FreeBSD. Although it's designed to work with interfaces provided by the Linux kernel, it can be utilized in other environments as well. It was specifically developed for embedded operating systems that have limited resources. The authors often refer to it as "The Swiss Army knife of Embedded Linux" because its single executable replaces the functionality of more than 300 common commands.

BusyBox provides a collection of stripped-down Unix tools packaged in a single executable file. For example, the ls command can be executed using /bin/busybox ls.

# Run a BusyBox container
docker run -d --rm --name busybox-test busybox sleep 3600

# List files using BusyBox
docker exec busybox-test /bin/busybox ls

To view the list of binaries included in BusyBox, you can run the busybox executable from Docker.

docker exec busybox-test /bin/busybox

Alpine Linux

Alpine Linux is a lightweight Linux distribution that prioritizes security. Alpine has one of the fastest boot times of any operating system. Considering its features, it's an excellent choice as a base image for your Docker images and is widely used in embedded devices and routers.

Phusion Baseimage / Passenger-docker

Phusion Baseimage, also known as Baseimage-docker, is a minimal Ubuntu base image that has been modified to be Docker-friendly. It consumes only 8.3 MB of RAM and is more lightweight than the standard Ubuntu image and more practical than Alpine and BusyBox for many applications.

In addition to being Ubuntu, it includes:

• Modifications specifically designed for Docker-friendliness.
• Administration tools that are particularly useful in the context of Docker.
• Mechanisms for easily running multiple processes without conflicting with the Docker philosophy.

You can find more detailed information in the official GitHub repository.

The team behind this project has also created a base image for running Ruby, Python, Node.js, and Meteor web apps called passenger-docker.

Distroless Images

Google's Distroless images are minimal base images that contain only the necessary components to run applications. They don't include package managers, shells, or any other unnecessary tools, which makes them smaller and more secure. Distroless images are available for various programming languages, including Python, Node.js, and Java.

Distroless images are smaller than most production-ready lightweight images. The smallest distroless image, gcr.io/distroless/static-debian12, is around 2 MiB. That's about 50% of the size of Alpine (~5 MiB) and less than 2% of the size of Debian (124 MiB).

Images have 4 tags:

• latest