Multi-Stage Docker Build Failing at Specific Stage — Fix

# Build with verbose output
docker build --progress=plain -t myapp . 2>&1 | tee build.log
 
# Target a specific stage to isolate the failure
docker build --target builder -t myapp-debug .
 
# Inspect the failing intermediate image
docker run -it myapp-debug /bin/sh

# BAD — minimal node image missing build tools
FROM node:20-alpine AS builder
RUN npm install  # fails: node-gyp needs python, make, g++
 
# GOOD — add build dependencies first
FROM node:20-alpine AS builder
RUN apk add --no-cache python3 make g++
RUN npm install

# Check if pip/npm can reach internet in CI
docker build --network=host -t myapp .
# or
docker build --build-arg HTTP_PROXY=$HTTP_PROXY -t myapp .

# BAD — typo in stage name
FROM node:20 AS builer        # typo: "builer"
RUN npm run build
 
FROM nginx:alpine
COPY --from=builder /app/dist /usr/share/nginx/html  # "builder" != "builer"
 
# GOOD — names must match exactly
FROM node:20 AS builder
RUN npm run build && ls /app/dist  # verify output exists
 
FROM nginx:alpine
COPY --from=builder /app/dist /usr/share/nginx/html

docker build --target builder -t debug-builder .
docker run --rm debug-builder ls /app/dist

# WRONG — ARG defined before FROM doesn't persist after it
ARG APP_VERSION=1.0.0
 
FROM node:20 AS builder
# $APP_VERSION is empty here!
 
# CORRECT — re-declare ARG in each stage that needs it
ARG APP_VERSION=1.0.0
 
FROM node:20 AS builder
ARG APP_VERSION      # re-declare (inherits the top-level default)
RUN echo "Building version $APP_VERSION"
RUN npm run build
 
FROM nginx:alpine
ARG APP_VERSION      # re-declare again if needed here
LABEL version="$APP_VERSION"
COPY --from=builder /app/dist /usr/share/nginx/html

# BAD — secret ends up in layer history
FROM alpine AS builder
ARG NPM_TOKEN
RUN echo "//registry.npmjs.org/:_authToken=$NPM_TOKEN" > ~/.npmrc
RUN npm install
 
# GOOD — secret never persists in layers
# syntax=docker/dockerfile:1
FROM alpine AS builder
RUN --mount=type=secret,id=npmrc,dst=/root/.npmrc \
    npm install

# Pass secret at build time
docker build \
  --secret id=npmrc,src=$HOME/.npmrc \
  -t myapp .

# Explicit platform
FROM --platform=linux/amd64 golang:1.22 AS builder
 
# Or build for target platform
# Build for linux/amd64 on any host:
# docker build --platform linux/amd64 -t myapp .

docker buildx create --use
docker buildx build \
  --platform linux/amd64,linux/arm64 \
  -t myregistry/myapp:latest \
  --push .

# BAD — copying everything first invalidates npm install cache
FROM node:20 AS builder
COPY . .           # ANY file change re-runs npm install
RUN npm install
 
# GOOD — copy dependency files first
FROM node:20 AS builder
COPY package.json package-lock.json ./
RUN npm install    # only re-runs if package.json changes
COPY . .
RUN npm run build

# Check .dockerignore
cat .dockerignore | grep config
 
# Verify files exist before build in CI
ls -la ./config
 
# Check if gitignored
git check-ignore -v config/

# If config/ was accidentally ignored, remove it or use negation
!config/

# 1. Build up to the failing stage
docker build --target <stage-before-failing> -t debug-img .
 
# 2. Run interactively inside that stage
docker run --rm -it debug-img /bin/sh
 
# 3. Manually run the failing command
RUN npm install  →  npm install
 
# 4. Check what's available
ls, env, which <tool>, <tool> --version