Think about how a professional chef prepares a high-end meal. They have a "prep station" and a "plating station." The prep station is where the chaos happens: there are potato peels everywhere, heavy-duty industrial peelers, raw scraps, and maybe some messy flour on the counter. It's essential for getting the food ready, but you would never imagine the chef carrying that entire messy table out to the dining room to serve the guest. They only bring the finished, plated dish.

Multi-stage Docker builds work exactly the same way. In the Ruby world, our "prep station" is the build environment where we install build-essential, gcc, and make just so we can compile native extensions for gems like nokogiri or pg. Once those gems are compiled, we don't need the compiler anymore. If we leave it in the image, we're basically carrying the potato peels and the industrial peeler to the customer's table. It makes the image bloated and, frankly, it's a security risk to leave a C compiler inside a production container.

Separating the Workshop from the Showroom

In a standard Dockerfile, everything you RUN stays in the final image. But with multi-stage builds, we use multiple FROM statements. The first stage is our workshop; the second is our showroom.

I've seen a lot of developers try to solve this by chaining commands with && and then running apt-get purge at the end of a single layer. It's tedious and error-prone. Multi-stage builds are much cleaner because we simply discard the entire first image and only "pluck" the files we actually need for the second one.

Putting the Multi-Stage Dockerfile into Practice

Let's look at a real scenario. Imagine we have a Ruby app that relies on the pg gem. To install it, we need the PostgreSQL development headers, but to run it, we only need the shared library.

# Stage 1: The Builder
FROM ruby:3.2-slim AS builder

# Install the heavy lifting tools
RUN apt-get update -qq && \
    apt-get install -y build-essential libpq-dev

WORKDIR /app
COPY Gemfile Gemfile.lock ./

# Install gems to the system path
RUN bundle install

# Stage 2: The Final Runtime
FROM ruby:3.2-slim

# Install ONLY the runtime library needed for the pg gem
RUN apt-get update -qq && \
    apt-get install -y libpq5 && \
    rm -rf /var/lib/apt/lists/*

WORKDIR /app

# Here is the magic: we copy the compiled gems from the builder stage
COPY --from=builder /usr/local/bundle /usr/local/bundle
COPY . .

CMD ["ruby", "app.rb"]

Notice a few things here. First, I named the first stage AS builder. This gives us a handle to refer back to later. Second, in the final stage, I used COPY --from=builder. This tells Docker: "Go back to that first image, grab the /usr/local/bundle folder where our gems live, and bring them over here."

The result? Your final image contains the Ruby runtime and your compiled gems, but it doesn't contain gcc, make, or the header files. I've seen this drop image sizes from 800MB down to 150MB in some Rails projects. That's a massive difference when you're pushing images to a registry or scaling pods in Kubernetes.

Handling the Gem Cache

One thing I should mention: by default, bundle install puts things in a cache. In a multi-stage build, if you only copy /usr/local/bundle, you're leaving the cache behind in the builder stage. This is actually exactly what you want. You don't need the .gem files in production; you only need the installed libraries. It's another way to keep your "plating station" spotless.

📋 Practical Task

Optimizing the 'RubyAnalytics' Image Size

You've been handed a Dockerfile for a service called RubyAnalytics. It currently uses a single-stage build that installs git and build-essential to handle some complex gem dependencies, but it leaves them in the final image, resulting in a bloated 900MB container.

Your Task: Rewrite the provided Dockerfile into a multi-stage build. You must ensure that the final image contains the installed gems and the application code, but does not contain build-essential or git.

# CURRENT BLOATED DOCKERFILE
FROM ruby:3.2-slim
RUN apt-get update -qq && apt-get install -y build-essential git
WORKDIR /app
COPY Gemfile Gemfile.lock ./
RUN bundle install
COPY . .
CMD ["ruby", "analytics_engine.rb"]

Requirements:

• Create a stage named builder.
• Use ruby:3.2-slim for both stages.
• Use COPY --from=builder to move the gems into the final stage.
• Ensure the final stage is clean of build-time dependencies.