Multi-stage builds for static sites in Nginx - Step-by-Step Execution

Process Flow - Multi-stage builds for static sites

Start: Define build stage

↓

Build static site files

↓

Start: Define final stage

↓

Copy built files from build stage

↓

Configure nginx to serve files

↓

Build final image

↓

Run container serving static site

This flow shows how Docker builds a static site in one stage, then copies only the needed files into a smaller nginx image to serve the site.

Execution Sample

Nginx

FROM node:18 AS build
WORKDIR /app
COPY . .
RUN npm install && npm run build

FROM nginx:alpine
COPY --from=build /app/dist /usr/share/nginx/html

This Dockerfile builds a static site with Node.js, then copies the built files into an nginx image to serve them.

Process Table

Step	Action	Stage	Files Present	Image Size Impact
1	Start build stage with node:18	build	Empty	Base node image size (~900MB)
2	Copy source files to /app	build	Source files copied	No size change yet
3	Run npm install	build	Node modules installed	Increases size by dependencies
4	Run npm run build	build	Built static files in /app/dist	Adds build output files
5	Start final stage with nginx:alpine	final	Empty	Small base image (~22MB)
6	Copy /app/dist from build stage to nginx html folder	final	Static files present	Adds only built files, keeps image small
7	Build final image	final	Static site ready to serve	Final image size small (~30MB)
8	Run container	final	Serving static site	Container runs nginx serving static files

💡 Final image built with only static files and nginx, keeping size small and efficient.

Status Tracker

Variable	Start	After Step 2	After Step 4	After Step 6	Final
Files in build stage	Empty	Source files	Source + node_modules + dist	N/A	N/A
Files in final stage	Empty	Empty	Empty	Copied dist files	Static site files only
Image size	~900MB base	~900MB	~950MB	~22MB base	~30MB final

Key Moments - 3 Insights

Why do we use two FROM lines in the Dockerfile?

Each FROM starts a new stage. The first builds the site, the second copies only the needed files to keep the final image small, as shown in steps 1 and 5 of the execution_table.

What happens if we copy all files instead of just /app/dist in step 6?

The final image would include unnecessary source and node_modules files, making it much larger. The execution_table step 6 shows only copying /app/dist keeps the image small.

Why is the final image size much smaller than the build stage?

Because the final stage uses a lightweight nginx base and copies only the built static files, avoiding large build tools and dependencies present in the build stage, as tracked in variable_tracker.

Visual Quiz - 3 Questions

Look at the execution_table at step 4, what files are present in the build stage?

A Source files only

B Source files, node_modules, and built static files

C Source files and node_modules only

D Empty

💡 Hint

Check the 'Files Present' column at step 4 in execution_table.

At which step does the final image start to include the static site files?

A Step 6

B Step 3

C Step 2

D Step 1

💡 Hint

Look for when files are copied into the final stage in execution_table.

If we skipped the build stage and copied source files directly to nginx, what would happen?

A The site would serve correctly with smaller image size

B The image size would be larger than build stage

C The site would fail because static files are not built

D Nginx would automatically build the site

💡 Hint

Refer to the purpose of the build stage in concept_flow and execution_table steps 3-4.

Concept Snapshot

Multi-stage builds use multiple FROM lines in Dockerfile.
First stage builds static files with tools (Node.js).
Second stage uses lightweight nginx image.
Copy only built files from build stage to final.
Keeps final image small and efficient.
Run container to serve static site with nginx.

Full Transcript

Multi-stage builds for static sites use Docker to separate building and serving. First, a build stage uses a Node.js image to install dependencies and build the static site files. Then, a final stage uses a small nginx image and copies only the built static files from the build stage. This keeps the final image small and efficient. The Dockerfile has two FROM lines, each starting a stage. The build stage creates the files, and the final stage serves them. This method avoids including unnecessary build tools and source files in the final image. The execution table shows each step: starting build, copying files, running build commands, starting final stage, copying built files, and running the container. The variable tracker shows how files and image size change. Key moments clarify why two stages are used, why only built files are copied, and why the final image is smaller. The quiz tests understanding of file presence, copying step, and consequences of skipping build. This approach is common for static sites to optimize Docker images.

Practice

1. What is the main benefit of using multi-stage builds for static sites with nginx?

easy

A. It automatically updates static files without rebuilding the image.

B. It allows running multiple nginx servers in one container.

C. It reduces the final image size by separating build and serve stages.

D. It enables dynamic content generation inside the nginx container.

Solution

1. Step 1: Understand multi-stage build purpose

   Multi-stage builds separate the build process from the final image, so only necessary files are included.

2. Step 2: Identify benefits for static sites

   This separation reduces the final image size and improves security by excluding build tools from the runtime image.

3. Final Answer:

   It reduces the final image size by separating build and serve stages. -> Option C

4. Quick Check:

   Multi-stage builds = smaller images [OK]

Hint: Remember: build tools stay out of final image for smaller size [OK]

Common Mistakes:

• Thinking multi-stage runs multiple nginx servers
• Believing static files update automatically without rebuild
• Confusing static site builds with dynamic content generation

2. Which Dockerfile snippet correctly copies static files from a builder stage to the nginx stage?

easy

A. COPY --to=builder /app/dist /usr/share/nginx/html

B. COPY /app/dist /usr/share/nginx/html --from=builder

C. COPY /usr/share/nginx/html /app/dist --from=builder

D. COPY --from=builder /app/dist /usr/share/nginx/html

Solution

1. Step 1: Recall correct COPY syntax for multi-stage

   The syntax is COPY --from=stage source_path destination_path.

2. Step 2: Match snippet to syntax

   COPY --from=builder /app/dist /usr/share/nginx/html uses COPY --from=builder /app/dist /usr/share/nginx/html which is correct.

3. Final Answer:

   COPY --from=builder /app/dist /usr/share/nginx/html -> Option D

4. Quick Check:

   COPY --from=stage source dest = correct [OK]

Hint: COPY uses --from=stage before source path [OK]

Common Mistakes:

• Placing --from after paths
• Using --to instead of --from
• Reversing source and destination paths

3. Given this Dockerfile snippet, what will be the size impact on the final image?

FROM node:18 AS builder
WORKDIR /app
COPY . .
RUN npm run build

FROM nginx:alpine
COPY --from=builder /app/dist /usr/share/nginx/html

medium

A. Final image will be small because only nginx and static files are included.

B. Final image will be empty because build files are not copied.

C. Final image will be large because node is included.

D. Final image will contain both node and nginx layers.

Solution

1. Step 1: Analyze multi-stage build layers

   The builder stage uses node to build files, but the final stage uses nginx:alpine only.

2. Step 2: Understand what is copied to final image

   Only the /app/dist folder from builder is copied into nginx image, so node and build tools are excluded.

3. Final Answer:

   Final image will be small because only nginx and static files are included. -> Option A

4. Quick Check:

   Multi-stage excludes build tools = smaller image [OK]

Hint: Final image excludes builder tools, so size stays small [OK]

Common Mistakes:

• Assuming node stays in final image
• Thinking build files are missing
• Believing both node and nginx layers combine

4. You wrote this Dockerfile but the static files are missing in the nginx container:

FROM node:18 AS builder
WORKDIR /app
COPY . .
RUN npm run build

FROM nginx:alpine
COPY /app/dist /usr/share/nginx/html

What is the error?

medium

A. COPY command misses --from=builder to copy from the build stage.

B. npm run build did not generate files in /app/dist.

C. nginx:alpine image does not support static files.

D. WORKDIR is not set in the nginx stage.

Solution

1. Step 1: Check COPY command in final stage

   The COPY command lacks --from=builder, so it copies from the current stage which is empty.

2. Step 2: Understand multi-stage copy syntax

   To copy files from builder stage, COPY must use --from=builder to access that stage's files.

3. Final Answer:

   COPY command misses --from=builder to copy from the build stage. -> Option A

4. Quick Check:

   Missing --from=builder causes empty copy [OK]

Hint: Always use --from=builder to copy from build stage [OK]

Common Mistakes:

• Forgetting --from=builder in COPY
• Assuming build files auto-copy without --from
• Blaming nginx image for missing files

5. You want to optimize your multi-stage Dockerfile for a static site by minimizing layers and image size. Which approach is best?

hard

A. Combine build and nginx in one stage to avoid copying files.

B. Use a builder stage to create static files, then copy only those files into a minimal nginx image.

C. Install node and build tools inside the nginx image to keep one image.

D. Copy the entire project folder into nginx image to ensure all files are present.

Solution

1. Step 1: Understand multi-stage build best practices

   Best practice is to separate build tools from runtime to keep images small and secure.

2. Step 2: Choose approach minimizing layers and size

   Using a builder stage to create static files, then copying only those files into a minimal nginx image achieves this.

3. Final Answer:

   Use a builder stage to create static files, then copy only those files into a minimal nginx image. -> Option B

4. Quick Check:

   Separate build and serve stages = optimized image [OK]

Hint: Build separately, copy only static files to nginx [OK]

Common Mistakes:

• Combining build and serve increases image size
• Installing build tools in nginx image adds unnecessary layers
• Copying entire project wastes space and layers