Builder pattern before multi-stage in Docker - Deep Dive

Overview - Builder pattern before multi-stage

What is it?

The builder pattern before multi-stage Docker builds is a way to create Docker images by separating the build process into distinct steps using multiple Dockerfiles or manual image layering. It helps manage complex builds by isolating build dependencies from the final image. This approach was common before Docker introduced multi-stage builds, which automate this process in a single Dockerfile.

Why it matters

Without this pattern, Docker images would often include unnecessary build tools and files, making them large and inefficient. The builder pattern before multi-stage allowed developers to keep final images small and secure by manually separating build and runtime environments. Without it, images would be bloated, slower to deploy, and harder to maintain.

Where it fits

Learners should first understand basic Docker concepts like Dockerfiles, images, and containers. After mastering this pattern, they can learn multi-stage builds, which simplify and improve the builder pattern. Later, they can explore advanced image optimization and CI/CD integration.

Mental Model

Core Idea

The builder pattern before multi-stage splits building and final image creation into separate steps to keep images small and clean.

Think of it like...

It's like cooking a meal in two kitchens: one kitchen prepares all the ingredients with messy tools, and the other kitchen only assembles the final dish cleanly for serving.

┌───────────────┐       ┌───────────────┐
│ Build Image   │──────▶│ Final Image   │
│ (with tools)  │       │ (clean, small)│
└───────────────┘       └───────────────┘

Process:
1. Build image compiles and prepares everything.
2. Final image copies only needed files from build image.

Build-Up - 7 Steps

1

Foundation

Understanding Docker Images and Layers

Concept: Learn what Docker images and layers are and how they build up a container.

Docker images are made of layers stacked on top of each other. Each command in a Dockerfile creates a new layer. Layers help reuse parts of images and save space. When you run a container, it uses these layers to create a running environment.

Result

You understand that Docker images are built step-by-step and that each step adds a layer.

Knowing how layers work helps you see why separating build steps matters for image size and efficiency.

2

Foundation

What is the Builder Pattern Conceptually

Concept: Introduce the idea of separating build and runtime environments manually.

The builder pattern means you first create a full image with all tools needed to build your app. Then, you create a second image that copies only the final app files from the first image. This keeps the final image small and clean.

Result

You see why two images are used: one for building, one for running.

Understanding this separation is key to managing image size and security before multi-stage builds.

3

Intermediate

Creating a Build Image Dockerfile

Concept: Write a Dockerfile that installs build tools and compiles the app.

Example Dockerfile for build image: FROM golang:1.20 WORKDIR /app COPY . . RUN go build -o myapp This image has Go compiler and builds the app binary.

Result

You get a Docker image with the compiled app and build tools.

Knowing how to create a build image is the first practical step in the builder pattern.

4

Intermediate

Creating a Final Image Dockerfile

Concept: Write a Dockerfile that copies only the built app from the build image.

Example Dockerfile for final image: FROM alpine:3.18 COPY --from=builder /app/myapp /usr/local/bin/myapp CMD ["myapp"] Note: Before multi-stage, you can't use --from, so you manually copy files from the build container using docker cp or export/import.

Result

You get a small image with only the app binary and minimal runtime dependencies.

Separating the final image reduces size and attack surface by excluding build tools.

5

Intermediate

Manual Copying Between Images Before Multi-Stage

🤔Before reading on: do you think Dockerfiles alone can copy files between images before multi-stage builds? Commit to yes or no.

Concept: Learn how to manually transfer build artifacts between images using container export and import.

Since Dockerfiles before multi-stage can't copy from other images, you build the app in one container, then copy files out: 1. Build the builder image: docker build -t builder . 2. Run container: docker create --name temp builder 3. Copy files: docker cp temp:/app/myapp ./myapp 4. Build final image with copied files: FROM alpine COPY myapp /usr/local/bin/myapp CMD ["myapp"] 5. Remove temp container: docker rm temp

Result

You successfully separate build and runtime by manual file copying.

Understanding manual copying reveals why multi-stage builds were a big improvement.

6

Advanced

Challenges and Limitations of Pre Multi-Stage Builder Pattern

🤔Before reading on: do you think manual builder pattern is easy to maintain and automate? Commit to yes or no.

Concept: Explore the difficulties of managing multiple Dockerfiles and manual steps.

Manual builder pattern requires extra scripts or commands to copy files between containers. It is error-prone, hard to automate, and increases build time. Also, it needs more disk space and careful cleanup of temporary containers.

Result

You see why this pattern is complex and fragile in real projects.

Knowing these challenges explains the motivation for multi-stage builds.

7

Expert

How Multi-Stage Builds Improved the Builder Pattern

🤔Before reading on: do you think multi-stage builds only simplify syntax or also improve build efficiency? Commit to one.

Concept: Understand how multi-stage builds combine builder pattern steps into one Dockerfile with better caching and automation.

Multi-stage builds let you define multiple FROM statements in one Dockerfile. You build your app in one stage, then copy artifacts to a later stage. This removes manual copying, reduces image size, and improves build speed with better caching.

Result

You get smaller, cleaner images with simpler Dockerfiles and automated build steps.

Recognizing multi-stage builds as an evolution of the builder pattern clarifies modern Docker best practices.

Under the Hood

Before multi-stage builds, Docker images were built independently. The builder pattern required creating a build image with all tools, running a container from it, extracting build artifacts manually, then creating a separate final image with only needed files. This process involved container lifecycle commands and manual file copying outside Dockerfile instructions.

Why designed this way?

Docker initially focused on simple image layering and did not support copying files between build stages in one Dockerfile. The builder pattern was a practical workaround to keep images small and secure. Multi-stage builds were introduced later to automate and simplify this process, reducing manual steps and errors.

┌───────────────┐       ┌───────────────┐       ┌───────────────┐
│ Build Dockerfile│────▶│ Build Image   │────▶│ Build Container│
└───────────────┘       └───────────────┘       └───────────────┘
         │                                             │
         │                                             ▼
         │                                   Extract build artifacts
         │                                             │
         ▼                                             ▼
┌───────────────┐       ┌───────────────┐       ┌───────────────┐
│ Final Dockerfile│◀────│ Final Image   │◀────│ Copy artifacts │
└───────────────┘       └───────────────┘       └───────────────┘

Myth Busters - 4 Common Misconceptions

Quick: Do you think you can copy files directly between images in a single Dockerfile before multi-stage builds? Commit yes or no.

Common Belief: You can copy files directly between images in one Dockerfile even before multi-stage builds.

Reality: Before multi-stage builds, Dockerfiles cannot copy files from one image to another directly. You must manually extract files from a container and then build a new image.

Why it matters: Believing this leads to confusion and wasted time trying to do impossible Dockerfile operations, causing build failures.

Quick: Is the builder pattern before multi-stage easy to automate fully with just Dockerfiles? Commit yes or no.

Common Belief: The builder pattern before multi-stage can be fully automated using only Dockerfiles.

Reality: It requires external scripts or manual commands to copy files between containers and images, so it is not fully automated within Dockerfiles alone.

Why it matters: Assuming full automation causes fragile build pipelines and unexpected manual steps.

Quick: Does using the builder pattern before multi-stage always produce small images? Commit yes or no.

Common Belief: Using the builder pattern before multi-stage always results in small final images.

Reality: If manual copying is not done carefully, leftover build files or tools can end up in the final image, making it large.

Why it matters: Misunderstanding this leads to bloated images that slow deployment and increase attack surface.

Quick: Do you think multi-stage builds only improve syntax, not build speed or caching? Commit yes or no.

Common Belief: Multi-stage builds only simplify Dockerfile syntax without affecting build performance.

Reality: Multi-stage builds improve caching and reduce build time by combining steps and avoiding redundant work.

Why it matters: Underestimating multi-stage builds misses their full benefits in CI/CD efficiency.

Expert Zone

1

Manual copying between containers before multi-stage builds can cause subtle bugs if file paths or permissions are mishandled.

2

Build cache invalidation is harder to control with separate Dockerfiles, leading to longer build times compared to multi-stage builds.

3

Cleaning up temporary containers and images is critical to avoid disk space issues in the manual builder pattern.

When NOT to use

Avoid the manual builder pattern now because multi-stage builds provide a cleaner, more reliable, and automated solution. Use multi-stage builds for all modern Docker projects. Legacy projects without multi-stage support may still use it, but migration is recommended.

Production Patterns

In production, teams use multi-stage builds to create minimal images with only runtime dependencies. They integrate builds into CI pipelines that cache layers efficiently. The manual builder pattern is mostly seen in legacy scripts or complex workflows requiring custom artifact extraction.

Connections

Continuous Integration/Continuous Deployment (CI/CD)

Build automation and artifact management

Understanding the builder pattern before multi-stage helps grasp how build artifacts are managed and optimized in CI/CD pipelines.

Software Build Systems (e.g., Make, Gradle)

Separating build and runtime artifacts

The builder pattern mirrors how build systems separate compiling code from packaging deliverables, showing a universal software engineering principle.

Manufacturing Assembly Lines

Sequential processing and quality control

Like assembly lines separate parts preparation from final assembly, the builder pattern separates building from packaging, improving efficiency and quality.

Common Pitfalls

#1 Including build tools in the final image, making it large and insecure.

Wrong approach:

FROM golang:1.20
WORKDIR /app
COPY . .
RUN go build -o myapp
CMD ["./myapp"]

Correct approach:

Use separate build and final images:

# Build image
FROM golang:1.20 AS builder
WORKDIR /app
COPY . .
RUN go build -o myapp

# Final image
FROM alpine:3.18
COPY --from=builder /app/myapp /usr/local/bin/myapp
CMD ["myapp"]

Root cause:

Not separating build and runtime environments leads to bloated images.

#2 Trying to copy files between images in one Dockerfile before multi-stage builds.

Wrong approach:

FROM alpine
COPY --from=builder /app/myapp /usr/local/bin/myapp

Correct approach:

Manually copy files:
1. Build builder image
2. Run container
3. docker cp container:/app/myapp ./
4. Build final image copying local file

Root cause:

Misunderstanding Dockerfile capabilities before multi-stage builds.

#3 Not cleaning up temporary containers after copying files, wasting disk space.

Wrong approach:

docker create --name temp builder
# forgot docker rm temp

Correct approach:

docker create --name temp builder
# copy files
docker rm temp

Root cause:

Neglecting container lifecycle management causes resource leaks.

Key Takeaways

The builder pattern before multi-stage builds separates building and final images manually to keep images small and secure.

It requires creating a build image with tools, running a container, extracting artifacts, and building a final image with only needed files.

This manual process is complex, error-prone, and hard to automate compared to modern multi-stage builds.

Multi-stage builds automate and improve this pattern by allowing multiple build stages in one Dockerfile with better caching and simplicity.

Understanding the builder pattern before multi-stage builds reveals why Docker evolved and helps appreciate current best practices.