How the build works: layers and stages
An image is a stack of layers: at the bottom, the layers of the base image from FROM; on top, one layer
per RUN and COPY line. Docker takes a layer from the cache if neither the line, nor the files it copies,
nor the layers above it have changed. The first changed layer is rebuilt, and so is everything below it. So
what changes rarely (the dependency list) is copied before what changes every day (code and texts).
A stage is FROM … AS name and the lines under it. Only the last stage ends up in the final image; we take
what we need from earlier stages with COPY --from=name:
stage build — node:24.22.1-alpine
├── node, npm
├── node_modules — about 200 MB
├── site sources
└── dist/ — finished pages
│
│ COPY --from=build
▼
final image — nginx:1.31.8-alpine
├── nginx
├── /etc/nginx/conf.d/default.conf
└── /usr/share/nginx/html — pages from dist/
Only the bottom part goes to the server: nginx on Alpine — tens of megabytes — and the site’s pages. Node, compilers and sources stay on the machine that ran the build.
Setup
The example is an Astro site: npm run build puts the pages into dist/. Another generator has its own
command and its own directory; everything else is the same.
Put .dockerignore next to the Dockerfile
.git .env .env.* node_modules distWithout it,
COPY . .dragsnode_modulesfrom the laptop,.envwith passwords and the whole git history into the build. How that ends — in .dockerignore.Write a two-stage Dockerfile
# Build stage: Node, dependencies, sources FROM node:24.22.1-alpine AS build WORKDIR /app COPY package.json package-lock.json ./ RUN npm ci COPY . . RUN npm run build # Final image: nginx and the finished pages FROM nginx:1.31.8-alpine COPY nginx.conf /etc/nginx/conf.d/default.conf COPY --from=build /app/dist/ /usr/share/nginx/html/ RUN nginx -tCOPY package.json package-lock.json ./andRUN npm cicome beforeCOPY . .: while the dependency list hasn’t changed, both layers come from the cache, and a text edit rebuilds onlyCOPY . .andnpm run build.npm cirather thannpm install: it installs exactly what’s recorded inpackage-lock.jsonand fails if the lock file has fallen behindpackage.json. So the image has the same versions you tested.Image tags carry the full version:
node:24.22.1-alpine, notnode:alpine— otherwise in a month the same build picks up a different Node (Docker, “A tag isn’t a version”).RUN nginx -tchecks the config during the build: an error stops the build, and an image with a broken config never appears.Write nginx.conf
server { listen 80; root /usr/share/nginx/html; error_page 404 /404.html; location / { try_files $uri $uri/ =404; } }Astro puts the
/about/page intoabout/index.html:try_files $uri $uri/finds it, and nginx addsindex.htmlby itself. The file fully replacesdefault.conffrom the nginx image.Build the image
docker build -t site:dev .Edit any page and build again. The dependency lines show
CACHEDin the output:=> CACHED [build 3/6] COPY package.json package-lock.json ./ => CACHED [build 4/6] RUN npm ciIf
npm ciran again though the dependencies didn’t change, thenCOPY . .sits above it orpackage.jsonchanged: an edit to theversionorscriptsfield is enough.Run it and open it
docker run --rm -d --name site-test -p 127.0.0.1:8080:80 site:dev curl -sI http://127.0.0.1:8080/ | head -1 # HTTP/1.1 200 OK docker rm -f site-testThe port is on
127.0.0.1: only we need this check, so it isn’t opened to the outside (A host-only port goes on 127.0.0.1).Tag it with the commit
docker tag site:dev site:$(git rev-parse --short HEAD)The commit tag shows which version is on the server, and it’s what you roll back to. How the image gets to the server without manual steps — Deploy without SSH.
If it doesn’t work
npm ci runs again after every text edit
- Cause
COPY . .sits aboveRUN npm ci: any changed file breaks the cache of that layer and every layer below.- Fix
- First
COPY package.json package-lock.json ./andRUN npm ci, thenCOPY . .— as in step 2.
The build starts with transferring context of hundreds of megabytes
- Cause
- There’s no
.dockerignore:node_modulesand.gitgo into the build context. - Fix
- Put a
.dockerignorenext to theDockerfile(.dockerignore).
npm ci can only install packages when your package.json and package-lock.json … are in sync
- Cause
- A dependency changed in
package.json, butpackage-lock.jsonwasn’t updated. - Fix
- Run
npm installon your machine and commit both files.npm ciin the build installs strictly from the lock file — that’s why we use it.
The image works on the laptop, but on the server — exec format error
- Cause
- The ARM laptop built the image for
arm64, and the server isamd64. - Fix
docker build --platform linux/amd64 …, or build on the server itself or in CI.
The build fails on the last step: nginx: [emerg] … in /etc/nginx/conf.d/default.conf:5
- Cause
- An error in
nginx.conf:RUN nginx -tchecks it during the build. - Fix
- Fix the line from the message. That’s the point: the broken config stays in the build, and the running site never gets it.
How to check
There’s no Node in the final image — it stayed in the build stage:
docker run --rm site:dev sh -c 'command -v node || echo "no node"'
# no node
The pages are in place; node_modules and sources aren’t:
docker run --rm site:dev ls /usr/share/nginx/html | head -3
docker run --rm site:dev ls /app
# ls: /app: No such file or directory
The size is nginx plus the site’s pages:
docker image ls site:dev --format '{{.Repository}}:{{.Tag}}\t{{.Size}}'