Multi-stage Builds و Non-root: image صغيرة ومن غير root

01 / ملخص الدرس

image حجمها أكتر من جيجا، فيها npm و typescript والـ npm token، وشغّالة root، و npm start ما بيوصّلش SIGTERM. بنفهم الـ multi-stage builds، والـ base images (full و slim و alpine و distroless)، والـ dev dependencies، و USER و non-root، والـ exec form والـ PID واحد، و tini، والـ pinning بالـ digest. والتحدي: imagecheck.js بيقسم الـ stages ويقدّر الحجم ويطلّع المشاكل، قصاد أربعتاشر حالة.

ضمن مسارباك إند Node.js للإنتاج — من تحت الصفر92 / 122

02 / شرح الدرس مكتوبًا

نص شرح المعلم والكود الذي كتبه ونتيجة تشغيله، بنفس ترتيب الدرس.

أهلًا بيك. الدرس اللي فات خلّى الـ build سريع، والـ context صغير. النهارده هنبص على الـ image النهائية نفسها: فيها إيه، وحجمها قد إيه، وبتشتغل بصلاحيات مين. الـ app بقى TypeScript، فمحتاج build. و Dockerfile dot naive ده اللي ناس كتير بتكتبه: FROM node twenty two. ARG اسمه NPM_TOKEN، علشان فيه package private. بيكتب الـ token في dot npmrc، و npm install. COPY الـ code، و npm run build. و CMD npm start. و dockerfile dot js هو الـ parser بتاع الدرس اللي فات، جاهز. بص على الـ Dockerfile كويس، وفكّر: فيه كام مشكلة؟ المشاكل: الحجم: node twenty two العادية لوحدها أكتر من جيجا، فيها compilers و Python و git. وفوقها كل الـ dependencies، ومنها typescript و eslint والـ test tools. كل ده ملوش لازمة وقت التشغيل. والـ image الكبيرة بتاخد وقت في الـ push والـ pull، وبتبطّأ الـ autoscaling. الأمان: كل tool جُوّه الـ image هي حاجة ممكن hacker يستخدمها لو دخل. وكل package فيها CVEs ممكن. الـ NPM_TOKEN: الـ ARG بيفضل في الـ image history، والـ dot npmrc اتكتب جُوّه layer. root: مفيش USER، فالـ app بيشتغل root جُوّه الـ container. و CMD npm start: لما Kubernetes يبعت SIGTERM علشان يقفل الـ container، الـ signal مش بيوصل للـ app صح.

الحل الأول: multi stage builds. Dockerfile واحد فيه أكتر من FROM. كل FROM بيبدأ stage جديد، وتقدر تسمّيه بـ AS. stage للـ dependencies: npm ci بكل حاجة، ومنها typescript. stage للـ build: بيكمّل منه، يعمل build، وبعدين npm prune omit dev يشيل الـ dev dependencies. والـ stage الأخير بيبدأ من base نضيفة خالص، وبياخد من اللي قبله الحاجات اللي محتاجها بس، بـ COPY from. والمهم: الـ image النهائية هي الـ stage الأخير بس. الـ stages اللي قبله بتتبني، بس مش بتتشحن. فـ typescript، والـ source code، وأي secret استخدمته في الـ build stage، مش موجودين في الـ image. وكمان BuildKit بيبني الـ stages اللي مش معتمدة على بعض في نفس الوقت، وتقدر تبني stage معين بـ target، زي stage للـ tests.

والـ base image: node twenty two: أكتر من جيجا. فيها كل حاجة. كويسة للـ build stage بس. slim: Debian صغيرة، حوالي مِيّتين ميجا. اختيار كويس وآمن. alpine: أصغر، بس بتستخدم musl بدل glibc. أغلب الحاجات شغّالة، بس شوية native modules بتعمل مشاكل أو بتبقى أبطأ. distroless من Google: فيها Node والـ libraries اللي محتاجها وبس. مفيش shell، ومفيش package manager، ومفيش curl. لو حد دخل، مش هيلاقي tools. والعيب: مش هتقدر تعمل docker exec وتفتح shell علشان تـ debug، فيه debug tags للحالة دي. وفيه حاجة مهمة: الـ tag زي twenty two slim بيتغير مع الوقت. لو عايز الـ build يبقى نفسه بالضبط، اعمل pin بالـ digest، وخلّي tool زي Renovate تغيّره لك.

الحل التاني: non root. الـ container مش virtual machine. الـ process جُوّاه شغّال على نفس الـ kernel بتاع الـ host. ولو root جُوّه، وفيه vulnerability في الـ runtime أو mount غلط، ممكن يبقى root على الـ host. في الـ node images فيه user جاهز اسمه node. وفي distroless فيه nonroot، والـ tag اللي آخره nonroot بيشغّله لوحده. اكتب USER قبل الـ CMD، وبعد أي حاجة محتاجة root زي apt get. والـ files اللي الـ app محتاج يكتب فيها، اعملها بـ chown. الـ non root ما يقدرش يفتح port أقل من ألف وأربعة وعشرين، فاستخدم تلات آلاف، والـ load balancer يوصّل عليه. ولما تشغّل: read only root filesystem، وشيل الـ capabilities، و no new privileges. و Kubernetes بيقدر يرفض أي container بيشتغل root.

وتالت حاجة: الـ PID واحد والـ signals. CMD npm start مكتوبة shell form: يعني Docker بيشغّل shell، والـ shell بيشغّل npm، و npm بيشغّل node. الـ SIGTERM بيروح للـ shell، وغالبًا مش بيوصل لـ node. فبعد عشر تواني Docker بيعمل SIGKILL، والـ requests اللي شغّالة بتتقطع. الحل: exec form، JSON array: CMD node و dist server dot js. كده node نفسه هو الـ PID واحد، وبياخد الـ signal على طول. وده مهم أوي لدرس الـ graceful shutdown. والـ PID واحد ليه مسؤولية كمان: يلم الـ zombie processes. لو الـ app بيعمل child processes، استخدم init صغير زي tini، أو docker run init. و NODE_ENV production: express وغيره بيشتغلوا أسرع وبيطبعوا errors أقل. ده الـ Dockerfile الجديد: تلات stages. deps فيه npm ci، و build بيعمل build و prune، و runtime مبني على distroless nonroot، بياخد node_modules و dist بس، و USER nonroot، و CMD exec form. والـ distroless node image الـ entrypoint بتاعها node أصلًا، فالـ CMD فيه اسم الـ file بس. والـ NPM_TOKEN اختفى. هنرجع له في درس BuildKit secrets. و check dot js بيشغّل الـ tool على الـ Dockerfiles. التحدي: اكتب imagecheck dot js. التفاصيل كلها في الكومنت، و test dot js فيه أربعتاشر حالة.

تمرين

imagecheck.js: parseStages بالأسماء والـ parent، و estimateSize للـ stage الأخير والـ chain بتاعه، و lintDockerfile بـ LATEST و NPM-INSTALL و SECRET و ADD-URL و UNKNOWN-STAGE و ROOT و SHELL-FORM و NPM-START و DEV-DEPS و BIG-BASE.

الحل. parseStages: كل FROM يبدأ stage، ولو الـ base اسم stage قبله، نربطه بيه وناخد الـ image بتاعته. الـ chain: steps الأب الأول وبعدين الابن. ده مهم، لأن FROM deps AS build معناها إن build فيه كل layers الـ deps. estimateSize: بيبص على آخر stage بس، لأن هو ده اللي بيتشحن. lint: rules على كل الـ stages، زي الـ secrets و typos الـ stages. و rules على آخر stage والـ chain بتاعه بس، زي الـ USER والـ CMD والـ dev dependencies. نشغّل check dot js على الاتنين.

imagecheck.js

// imagecheck.js: بيقسم الـ Dockerfile لـ stages، وبيقدّر حجم الـ image النهائية، وبيطلّع المشاكل
import { parseDockerfile } from "./dockerfile.js";

export const BASES = {
  "node:22": 1100,
  "node:22-slim": 220,
  "node:22-alpine": 160,
  "gcr.io/distroless/nodejs22-debian12": 130,
  "gcr.io/distroless/nodejs22-debian12:nonroot": 130,
};

export function parseStages(text) {
  const stages = [];
  for (const s of parseDockerfile(text)) {
    if (s.op === "FROM") {
      const parts = s.args.split(/\s+/).filter((p) => !p.startsWith("--"));
      const name = parts.length >= 3 && parts[1].toLowerCase() === "as" ? parts[2] : null;
      const parent = stages.find((x) => x.name === parts[0]) ?? null;
      stages.push({ index: stages.length, name, base: parts[0], parent, image: parent ? parent.image : parts[0], line: s.line, steps: [] });
    } else if (stages.length) stages.at(-1).steps.push(s);
  }
  return stages;
}

// الـ steps بتاعة الـ stage وكل الـ stages اللي هو مبني عليها، من الأقدم للأحدث
const chain = (st) => (st.parent ? [...chain(st.parent), ...st.steps] : st.steps);

export function estimateSize(stages, bases = BASES) {
  const last = stages.at(-1);
  let mb = bases[last.image] ?? 500;
  for (const s of chain(last)) {
    if (s.op === "RUN") mb += /npm (ci|install)/.test(s.args) ? (/--omit=dev|--production/.test(s.args) ? 40 : 180) : /apt-get|apk/.test(s.args) ? 80 : 1;
    if (s.op === "COPY" || s.op === "ADD") mb += /--from=/.test(s.args) ? (/node_modules/.test(s.args) ? 40 : 2) : 1;
    if (s.op === "RUN" && /npm prune --omit=dev/.test(s.args)) mb -= 140;
  }
  return mb;
}

const SECRETY = /(PASSWORD|SECRET|TOKEN|API_KEY|PRIVATE_KEY)/i;
const SMALL = /(slim|alpine|distroless)/;

export function lintDockerfile(text) {
  const stages = parseStages(text);
  const out = [];
  const add = (rule, line, severity, msg) => out.push({ rule, line, severity, msg });
  if (!stages.length) return [{ rule: "NO-FROM", line: 1, severity: "ERROR", msg: "مفيش FROM" }];
  const names = new Set();

  for (const st of stages) {
    if (!st.parent && !st.base.includes("@sha256:") && (!st.base.includes(":") || st.base.endsWith(":latest"))) add("LATEST", st.line, "WARN", "اكتب tag محدد (أو digest)، مش latest");
    for (const s of st.steps) {
      if (s.op === "RUN" && /\bnpm install\b/.test(s.args)) add("NPM-INSTALL", s.line, "WARN", "استخدم npm ci: بيمشي على الـ lock file بالضبط");
      if ((s.op === "ENV" || s.op === "ARG") && SECRETY.test(s.args.split(/[=\s]/)[0])) add("SECRET", s.line, "ERROR", "secret في ENV أو ARG بيفضل في الـ image أو الـ history: استخدم BuildKit secrets");
      if (s.op === "ADD" && /https?:\/\//.test(s.args)) add("ADD-URL", s.line, "WARN", "ADD من URL من غير checksum: نزّله بـ RUN curl وتأكد من الـ hash");
      const from = /--from=(\S+)/.exec(s.args)?.[1];
      if (s.op === "COPY" && from && !names.has(from) && !(/^\d+$/.test(from) && Number(from) < st.index) && !from.includes("/") && !from.includes(":"))
        add("UNK
…

المخرجات

$ node check.js app/Dockerfile.naive app/Dockerfile

===== app/Dockerfile.naive =====
stages: #0 | الأخير مبني على node:22 | حوالي 1283 MB
  سطر  1 ERROR ROOT         الـ container هيشتغل root: ضيف USER node أو nonroot
  سطر  1 INFO  BIG-BASE     node:22 كبيرة: جرّب slim أو distroless
  سطر  3 ERROR SECRET       secret في ENV أو ARG بيفضل في الـ image أو الـ history: استخدم BuildKit secrets
  سطر  5 WARN  NPM-INSTALL  استخدم npm ci: بيمشي على الـ lock file بالضبط
  سطر  5 WARN  DEV-DEPS     الـ dev dependencies هتفضل في الـ image النهائية
  سطر  9 WARN  SHELL-FORM   اكتبه JSON array علشان SIGTERM يوصل للـ app
  سطر  9 WARN  NPM-START    npm مش بيوصّل الـ signals كويس: شغّل node على طول

===== app/Dockerfile =====
stages: deps → build → runtime | الأخير مبني على gcr.io/distroless/nodejs22-debian12:nonroot | حوالي 172 MB
  مفيش مشاكل

الـ naive: حوالي ألف وتلتمية ميجا، وسبع مشاكل: root، و base كبيرة، والـ token في ARG، و npm install، والـ dev dependencies، و shell form، و npm start. الجديد: تلات stages، والأخير مبني على distroless nonroot، وحوالي مِيّة وسبعين ميجا، ومفيش مشاكل. يعني أصغر سبع مرات تقريبًا. وخلي بالك: الأرقام هنا تقدير. على machine فيها Docker هتشوف الرقم الحقيقي بـ docker images، والـ layers بـ docker history. وفيه tools حقيقية بتعمل اللي عملناه: hadolint للـ lint، و Trivy و Docker Scout للـ CVEs. ونشغّل test dot js.

imagecheck.js

المخرجات

$ node test.js
✅ parseStages: الأسماء و base و index، و as صغيرة، و --platform بيتشال 
✅ parseStages: stage مبني على stage ← parent و image بتاعة الأصل، و steps كل واحد بتاعته 
✅ estimateSize: الـ naive ألف ومِيّتين تلاتة وتمانين، والـ multi مِيّة اتنين وسبعين، و base مش معروفة خمسمية 1283 / 172
✅ ROOT: مفيش USER ← ERROR على سطر الـ FROM 
✅ ROOT: USER root و USER 0:0 ← ERROR على سطر الـ USER، و USER node ← لأ 
✅ ROOT: base آخرها :nonroot، أو USER في الـ stage الأب ← مش root 
✅ LATEST: node و node:latest آه، و node:22 و digest و stage لأ 
✅ SECRET: ARG NPM_TOKEN و ENV DB_PASSWORD ← ERROR، و ENV NODE_ENV لأ 
✅ SHELL-FORM و NPM-START: CMD npm start ← الاتنين، و CMD JSON بـ node ← لأ 
✅ DEV-DEPS: npm ci في الأخير ← WARN، و --omit=dev أو NODE_ENV أو prune ← لأ، و npm ci في stage تاني بس ← لأ 
✅ NPM-INSTALL و ADD-URL 
✅ UNKNOWN-STAGE: typo ← ERROR، و رقم stage قبله و image ← لأ 
✅ BIG-BASE: INFO للـ node:22 بس 
✅ الـ naive: السبع مشاكل بالضبط ومترتبين بالسطر، والـ multi نضيف ROOT,BIG-BASE,SECRET,NPM-INSTALL,DEV-DEPS,SHELL-FORM,NPM-START

14/14

كله نجح. الـ app دلوقتي في image نضيفة. بس الـ app لوحده مش كفاية: محتاج Postgres و Redis. الدرس الجاي: docker compose، والـ networks، والـ services بتلاقي بعض إزاي بالاسم، و depends on، وليه الـ app بيقع لما الـ database لسه بتقوم.

dockerfile.js

// dockerfile.js: الـ parser بتاع الدرس اللي فات: كل instruction بالـ op والـ args ورقم السطر
export function parseDockerfile(text) {
  const steps = [];
  const lines = text.split("\n");
  for (let i = 0; i < lines.length; i++) {
    const start = i + 1;
    let l = lines[i].trim();
    if (!l || l.startsWith("#")) continue;
    while (l.endsWith("\\") && i + 1 < lines.length) l = l.slice(0, -1).trim() + " " + lines[++i].trim();
    const [op, ...rest] = l.split(/\s+/);
    steps.push({ op: op.toUpperCase(), args: rest.join(" "), line: start });
  }
  return steps;
}

app/Dockerfile.naive

FROM node:22
WORKDIR /app
ARG NPM_TOKEN
COPY package.json package-lock.json ./
RUN echo "//registry.npmjs.org/:_authToken=$NPM_TOKEN" > .npmrc && npm install
COPY . .
RUN npm run build
EXPOSE 3000
CMD npm start

app/Dockerfile

# syntax=docker/dockerfile:1

# stage واحد: الـ dependencies كلها، ومعاها dev (typescript وغيره)
FROM node:22-slim AS deps
WORKDIR /app
COPY package.json package-lock.json ./
RUN npm ci

# stage اتنين: build، وبعدين نشيل الـ dev dependencies
FROM deps AS build
COPY tsconfig.json ./
COPY src ./src
RUN npm run build && npm prune --omit=dev

# الـ stage الأخير بس هو اللي بيبقى الـ image: من غير npm ولا shell ولا compiler
FROM gcr.io/distroless/nodejs22-debian12:nonroot AS runtime
WORKDIR /app
ENV NODE_ENV=production
COPY --from=build /app/node_modules ./node_modules
COPY --from=build /app/dist ./dist
USER nonroot
EXPOSE 3000
CMD ["dist/server.js"]

check.js

// check.js: بيفحص كل Dockerfile: المشاكل، والـ image النهائية مبنية على إيه، وحجمها التقريبي
import { readFileSync } from "node:fs";
import { lintDockerfile, parseStages, estimateSize } from "./imagecheck.js";

for (const f of process.argv.slice(2)) {
  const text = readFileSync(f, "utf8");
  const stages = parseStages(text);
  const last = stages.at(-1);
  console.log(`\n===== ${f} =====`);
  console.log(`stages: ${stages.map((s) => s.name ?? `#${s.index}`).join(" → ")} | الأخير مبني على ${last.image} | حوالي ${estimateSize(stages)} MB`);
  const found = lintDockerfile(text);
  for (const x of found) console.log(`  سطر ${String(x.line).padStart(2)} ${x.severity.padEnd(5)} ${x.rule.padEnd(12)} ${x.msg}`);
  if (!found.length) console.log("  مفيش مشاكل");
}

test.js

import { readFileSync } from "node:fs";
import { parseStages, estimateSize, lintDockerfile } from "./imagecheck.js";

let ok = 0, all = 0;
const check = (name, cond, extra = "") => { all++; if (cond) ok++; console.log(cond ? "✅" : "❌", name, extra); };
const rules = (t) => lintDockerfile(t).map((f) => f.rule);
const has = (t, r) => rules(t).includes(r);
const ONE = (body, from = "node:22-slim") => `FROM ${from}\nUSER node\n${body}\nCMD ["node", "x.js"]`;

const st = parseStages("FROM --platform=linux/amd64 node:22-slim as deps\nRUN npm ci\nFROM deps AS build\nRUN npm run build\nFROM gcr.io/distroless/nodejs22-debian12:nonroot\nCOPY --from=build /app/dist ./dist");
check("parseStages: الأسماء و base و index، و as صغيرة، و --platform بيتشال", st.length === 3 && st[0].name === "deps" && st[0].base === "node:22-slim" && st[1].name === "build" && st[2].name === null && st[2].index === 2);
check("parseStages: stage مبني على stage ← parent و image بتاعة الأصل، و steps كل واحد بتاعته", st[1].parent === st[0] && st[1].image === "node:22-slim" && st[0].parent === null && st[0].steps.length === 1 && st[1].steps[0].args === "npm run build" && st[2].steps[0].line === 6);
const naive = readFileSync("app/Dockerfile.naive", "utf8"), multi = readFileSync("app/Dockerfile", "utf8");
check("estimateSize: الـ naive ألف ومِيّتين تلاتة وتمانين، والـ multi مِيّة اتنين وسبعين، و base مش معروفة خمسمية", estimateSize(parseStages(naive)) === 1283 && estimateSize(parseStages(multi)) === 172 && estimateSize(parseStages("FROM foo:1")) === 500, `${estimateSize(parseStages(naive))} / ${estimateSize(parseStages(multi))}`);

const noUser = lintDockerfile('FROM node:22-slim\nCMD ["node", "x.js"]');
check("ROOT: مفيش USER ← ERROR على سطر الـ FROM", noUser.some((f) => f.rule === "ROOT" && f.line === 1 && f.severity === "ERROR"));
check("ROOT: USER root و USER 0:0 ← ERROR على سطر الـ USER، و USER node ← لأ", lintDockerfile('FROM node:22-slim\nUSER root\nCMD ["node"]').find((f) => f.rule === "ROOT")?.line === 2 && has('FROM node:22-slim\nUSER 0:0\nCMD ["node"]', "ROOT") && !has(ONE(""), "ROOT"));
check("ROOT: base آخرها :nonroot، أو USER في الـ stage الأب ← مش root", !has('FROM gcr.io/distroless/nodejs22-debian12:nonroot\nCMD ["x.js"]', "ROOT") && !has('FROM node:22-slim AS a\nUSER node\nFROM a\nCMD ["node"]', "ROOT"));
check("LATEST: node و node:latest آه، و node:22 و digest و stage لأ", has(ONE("", "node"), "LATEST") && has(ONE("", "node:latest"), "LATEST") && !has(ONE(""), "LATEST") && !has(ONE("", "node@sha256:abc123"), "LATEST") && !has('FROM node:22-slim AS a\nFROM a\nUSER node\nCMD ["node"]', "LATEST"));
check("SECRET: ARG NPM_TOKEN و ENV DB_PASSWORD ← ERROR، و ENV NODE_ENV لأ", has(ONE("ARG NPM_TOKEN"), "SECRET") && has(ONE("ENV DB_PASSWORD=x"), "SECRET") && !has(ONE("ENV NODE_ENV=production"), "SECRET"));
check("SHELL-FORM و NPM-START: CMD npm start ← الاتنين، و CMD JSON بـ node ← لأ", has("FROM node:22-slim\nUSER node\nCMD npm start", "SHELL-FORM") && has('FROM node:22-slim\n
…

03 / دروس المسار (122)