basforge

Search titles, text and the “If it doesn’t work” cases.

    RU

    Your own image: a multi-stage build of a static site

    Build the site in one Dockerfile stage and put only the result into the image: nginx and the finished pages, without Node, node_modules or sources. Line order decides how long a rebuild takes: copy the dependencies before the code, and a text edit won’t rerun npm ci.

    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.

    1. Put .dockerignore next to the Dockerfile

      .git
      .env
      .env.*
      node_modules
      dist

      Without it, COPY . . drags node_modules from the laptop, .env with passwords and the whole git history into the build. How that ends — in .dockerignore.

    2. 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 -t

      COPY package.json package-lock.json ./ and RUN npm ci come before COPY . .: while the dependency list hasn’t changed, both layers come from the cache, and a text edit rebuilds only COPY . . and npm run build.

      npm ci rather than npm install: it installs exactly what’s recorded in package-lock.json and fails if the lock file has fallen behind package.json. So the image has the same versions you tested.

      Image tags carry the full version: node:24.22.1-alpine, not node:alpine — otherwise in a month the same build picks up a different Node (Docker, “A tag isn’t a version”).

      RUN nginx -t checks the config during the build: an error stops the build, and an image with a broken config never appears.

    3. 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 into about/index.html: try_files $uri $uri/ finds it, and nginx adds index.html by itself. The file fully replaces default.conf from the nginx image.

    4. Build the image

      docker build -t site:dev .

      Edit any page and build again. The dependency lines show CACHED in the output:

       => CACHED [build 3/6] COPY package.json package-lock.json ./
       => CACHED [build 4/6] RUN npm ci

      If npm ci ran again though the dependencies didn’t change, then COPY . . sits above it or package.json changed: an edit to the version or scripts field is enough.

    5. 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-test

      The 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).

    6. 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 above RUN npm ci: any changed file breaks the cache of that layer and every layer below.
    Fix
    First COPY package.json package-lock.json ./ and RUN npm ci, then COPY . . — as in step 2.

    The build starts with transferring context of hundreds of megabytes

    Cause
    There’s no .dockerignore: node_modules and .git go into the build context.
    Fix
    Put a .dockerignore next to the Dockerfile (.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, but package-lock.json wasn’t updated.
    Fix
    Run npm install on your machine and commit both files. npm ci in 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 is amd64.
    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 -t checks 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}}'