basforge

Ищем по названиям, тексту и разборам «Если не работает».

    EN

    Свой образ: многоступенчатая сборка статического сайта

    Собираем сайт в одной стадии Dockerfile, а в образ кладём только результат: nginx и готовые страницы, без Node, node_modules и исходников. Порядок строк решает, сколько ждать пересборки: зависимости копируем раньше кода, и правка текста не запускает npm ci заново.

    Как устроена сборка: слои и стадии

    Образ — стопка слоёв: внизу слои базового образа из FROM, сверху — по слою на каждую строку RUN и COPY. Docker берёт слой из кэша, если не изменились ни строка, ни файлы, которые она копирует, ни слои выше. Первый изменённый слой пересобирается, и все ниже — тоже. Поэтому то, что меняется редко (список зависимостей), копируем раньше того, что меняется каждый день (код и тексты).

    Стадия — это FROM … AS имя и строки под ним. В итоговый образ попадает только последняя стадия, а из предыдущих мы забираем нужное через COPY --from=имя:

    стадия build — node:24.22.1-alpine
    ├── node, npm
    ├── node_modules — около 200 МБ
    ├── исходники сайта
    └── dist/ — готовые страницы
            │
            │ COPY --from=build
            ▼
    итоговый образ — nginx:1.31.8-alpine
    ├── nginx
    ├── /etc/nginx/conf.d/default.conf
    └── /usr/share/nginx/html — страницы из dist/

    На сервер уходит только нижняя часть: nginx на Alpine — десятки мегабайт — и страницы сайта. Node, компиляторы и исходники остаются на машине, где шла сборка.

    Настройка

    Пример — сайт на Astro: npm run build кладёт страницы в dist/. У другого генератора своя команда и свой каталог, остальное то же.

    1. Кладём .dockerignore рядом с Dockerfile

      .git
      .env
      .env.*
      node_modules
      dist

      Без него COPY . . тащит в сборку node_modules с ноутбука, .env с паролями и всю историю git. Чем это кончается — в «.dockerignore».

    2. Пишем Dockerfile в две стадии

      # Стадия сборки: Node, зависимости, исходники
      FROM node:24.22.1-alpine AS build
      WORKDIR /app
      COPY package.json package-lock.json ./
      RUN npm ci
      COPY . .
      RUN npm run build
      
      # Итоговый образ: nginx и готовые страницы
      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 ./ и RUN npm ci стоят до COPY . .: пока список зависимостей не менялся, оба слоя берутся из кэша, и правка текста пересобирает только COPY . . и npm run build.

      npm ci, а не npm install: он ставит ровно то, что записано в package-lock.json, и падает, если lock-файл отстал от package.json. Так в образе те же версии, что проверяли.

      Теги образов — с полной версией: node:24.22.1-alpine, а не node:alpine — иначе через месяц та же сборка возьмёт другой Node («Docker», «Тег — не версия»).

      RUN nginx -t проверяет конфиг при сборке: ошибка останавливает сборку, и образ со сломанным конфигом не появляется.

    3. Пишем nginx.conf

      server {
          listen 80;
          root /usr/share/nginx/html;
          error_page 404 /404.html;
      
          location / {
              try_files $uri $uri/ =404;
          }
      }

      Astro кладёт страницу /about/ в about/index.html: try_files $uri $uri/ находит её, index.html nginx подставляет сам. Файл заменяет default.conf из образа nginx целиком.

    4. Собираем образ

      docker build -t site:dev .

      Правим любую страницу и собираем ещё раз. В выводе у зависимостей — CACHED:

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

      Если npm ci пошёл заново, а зависимости не меняли, — значит, COPY . . стоит выше него или изменился package.json: хватает правки поля version или scripts.

    5. Запускаем и открываем

      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

      Порт — на 127.0.0.1: проверка нужна только нам, наружу его не открываем («Порт только для хоста — на 127.0.0.1»).

    6. Ставим тег по коммиту

      docker tag site:dev site:$(git rev-parse --short HEAD)

      По тегу коммита видно, что за версия на сервере, и к нему откатываемся. Как образ попадает на сервер без ручных шагов — «Деплой без SSH».

    Если не работает

    npm ci идёт заново после каждой правки текста

    Причина
    COPY . . стоит выше RUN npm ci: любой изменённый файл ломает кэш этого слоя и всех ниже.
    Делаем
    Сначала COPY package.json package-lock.json ./ и RUN npm ci, потом COPY . . — как в шаге 2.

    Сборка начинается с transferring context на сотни мегабайт

    Причина
    Нет .dockerignore: в контекст сборки уходят node_modules и .git.
    Делаем
    Кладём .dockerignore рядом с Dockerfile («.dockerignore»).

    npm ci can only install packages when your package.json and package-lock.json … are in sync

    Причина
    В package.json поменяли зависимость, а package-lock.json не обновили.
    Делаем
    npm install на своей машине и коммит обоих файлов. npm ci в сборке ставит строго по lock-файлу — поэтому его и берём.

    На ноутбуке образ работает, на сервере — exec format error

    Причина
    Ноутбук на ARM собрал образ под arm64, а сервер — amd64.
    Делаем
    docker build --platform linux/amd64 … или сборка на самом сервере либо в CI.

    Сборка падает на последнем шаге: nginx: [emerg] … in /etc/nginx/conf.d/default.conf:5

    Причина
    Ошибка в nginx.conf: RUN nginx -t проверяет его при сборке.
    Делаем
    Правим строку из сообщения. Так и задумано: сломанный конфиг остаётся в сборке, а работающий сайт его не получает.

    Как проверить

    В итоговом образе нет Node — он остался в стадии сборки:

    docker run --rm site:dev sh -c 'command -v node || echo "node нет"'
    # node нет

    Страницы на месте, node_modules и исходников нет:

    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

    Размер — nginx плюс страницы сайта:

    docker image ls site:dev --format '{{.Repository}}:{{.Tag}}\t{{.Size}}'