ফুল-স্ট্যাক অ্যাপ Docker-এ — multi-stage build আর compose

১ · কোন অংশ কোন container-এ — বাজারঘরের মানচিত্র

আগের পর্বগুলোতে “বাজারঘর” নামের কাল্পনিক অনলাইন দোকান টুকরো টুকরো তৈরি হয়েছে: Next.js-এর দোকানের পাতা, Express-এর API, পর্ব ৩৯-এর Prisma, পর্ব ৪৪-এর Redis আর পর্ব ৬২-এর BullMQ worker. এখন প্রশ্ন: এই সব একসাথে অন্য কম্পিউটারে, একইভাবে চালাবেন কীভাবে? এখানে Docker আসে।

Container, image, layer আর মূল কমান্ডগুলো এই কোর্সে আবার শেখানো হবে না। সেগুলো Cloud & DevOps কোর্সে বিস্তারিত আছে: Docker image আর layer, ভালো Dockerfile, container চালানো আর Docker Compose. এক লাইনে মনে করিয়ে দিই: image হলো অ্যাপ আর তার সব নির্ভরতার স্থির প্যাকেট, container হলো সেই প্যাকেট থেকে চালানো একটি বিচ্ছিন্ন process. এই পর্বের কাজ সেই জ্ঞান একটি আসল ফুল-স্ট্যাক অ্যাপে প্রয়োগ করা।

২ · Next.js-এর multi-stage Dockerfile — deps, build আর runner

প্রথমে ভুল পথটি দেখি, যা অনেক tutorial আর AI প্রথমে লেখে। একটি ধাপ, পুরো Node image, সব কিছু কপি:

FROM node:26
WORKDIR /app
COPY . .
RUN npm install
RUN npm run build
CMD ["npm", "start"]

চলে ঠিকই, কিন্তু image-এ থেকে যায় compiler-সহ পুরো Debian, সব devDependency, সোর্স কোড, build cache, আর .dockerignore না থাকলে আপনার .env-ও। এখানে সমাধান multi-stage build: একাধিক FROM, প্রতিটি একটি ধাপ, আর শেষ ধাপে শুধু চালানোর জন্য যা লাগে তা কপি। Next.js-এর standalone output এ কাজে বড় সাহায্য করে। nextjs.org-এর output পাতা অনুযায়ী output: 'standalone' দিলে build একটি .next/standalone ফোল্ডার বানায়, যাতে একটি ছোট server.js আর trace করে বের করা শুধু দরকারি node_modules থাকে; public আর .next/static হাতে কপি করতে হয়, আর PORT ও HOSTNAME environment variable দিয়ে ঠিকানা বদলানো যায়।

import type { NextConfig } from 'next';

const nextConfig: NextConfig = {
  output: 'standalone',
};

export default nextConfig;

# syntax=docker/dockerfile:1

# ---- ধাপ ১: শুধু dependency ----
FROM node:26-slim AS deps
WORKDIR /app
COPY package.json package-lock.json ./
RUN npm ci

# ---- ধাপ ২: build ----
FROM node:26-slim AS build
WORKDIR /app
COPY --from=deps /app/node_modules ./node_modules
COPY . .
ARG NEXT_PUBLIC_SHOP_NAME
ENV NEXT_PUBLIC_SHOP_NAME=$NEXT_PUBLIC_SHOP_NAME
RUN npm run build

# ---- ধাপ ৩: runner ----
FROM node:26-slim AS runner
WORKDIR /app
ENV NODE_ENV=production PORT=3000 HOSTNAME=0.0.0.0
COPY --from=build --chown=node:node /app/.next/standalone ./
COPY --from=build --chown=node:node /app/.next/static ./.next/static
COPY --from=build --chown=node:node /app/public ./public
USER node
EXPOSE 3000
CMD ["node", "server.js"]

তিনটি জিনিস খেয়াল করুন। HOSTNAME=0.0.0.0 না দিলে server শুধু container-এর ভেতরের localhost-এ শুনতে পারে, বাইরে থেকে পৌঁছানো যায় না। USER node: official Node image-এ node নামের সাধারণ user আগে থেকেই থাকে, তাই non-root চালাতে নতুন user বানাতে হয়নি। আর CMD exec form-এ (JSON array), যাতে node নিজেই process হয়, মাঝে কোনো shell না থাকে; অংশ ৮-এ এর গুরুত্ব দেখবেন। ধাপে ধাপে কী ঘটে:

#9 [deps 3/4] COPY package.json package-lock.json ./
#10 [deps 4/4] RUN npm ci
#10 32.07 added 28 packages, and audited 29 packages in 32s
#10 DONE 33.5s

#11 [build 3/5] COPY --from=deps /app/node_modules ./node_modules
#12 [build 4/5] COPY . .
#13 [build 5/5] RUN npm run build
#13 2.031 ✓ Compiled successfully in 1334ms
#13 4.907 Route (app)
#13 4.907 ┌ ƒ /
#13 4.907 ├ ○ /_not-found
#13 4.907 └ ƒ /api/health
#13 DONE 5.4s

server.js          ← ছোট Node server
package.json
node_modules/      ← 39M, শুধু trace করা অংশ
.next/server/      ← render-এর কোড
(public আর .next/static আলাদা করে কপি)

#14 [runner 3/5] COPY --from=build --chown=node:node /app/.next/standalone ./
#15 [runner 4/5] COPY --from=build --chown=node:node /app/.next/static ./.next/static
#16 [runner 5/5] COPY --from=build --chown=node:node /app/public ./public
compiler, devDependency, সোর্স: কিছুই আসেনি

$ docker image ls bz80-web
IMAGE            DISK USAGE   CONTENT SIZE
bz80-web:multi        407MB         97.8MB
bz80-web:naive       2.65GB          669MB
$ docker run --rm bz80-web:multi whoami
node
$ docker run --rm bz80-web:naive whoami
root

“Disk usage” হলো image খোলা অবস্থায় disk-এ কতটা জায়গা নেয়, আর “content size” হলো registry থেকে নামানোর সময়কার সংকুচিত আকার। Server-এ deploy-এর সময় দ্বিতীয়টি network-এ যায়। নিচের block ল্যাবের মাপ থেকে হিসাব করে, ধরে নেওয়া 20 Mbit/s গতিতে কত সেকেন্ড লাগবে:

// এই পর্বের ল্যাবের সত্যিকারের মাপ (docker image ls, একটি local run)
// disk = খোলা অবস্থায় জায়গা, content = registry থেকে নামানোর (সংকুচিত) আকার, MB
const images = [
  ["web naive (node:26, 1 stage)", 2650, 669],
  ["web multi-stage (standalone)", 407, 97.8],
  ["api slim, --omit=dev", 841, 187],
  ["api slim, --omit=dev,optional", 483, 117],
  ["api alpine, same Dockerfile", 382, 93.7],
  ["base node:26-slim only", 353, 85.7],
];
const mbps = 20;      // ধরে নেওয়া: server-এর download গতি 20 Mbit/s
const servers = 3;    // ধরে নেওয়া: একই image তিনটি server-এ নামবে
const naive = images[0][2];
console.log("image".padEnd(30), "disk".padStart(6), "pull".padStart(6), "x naive", " secs@20Mbps", " 3 servers");
for (const [name, disk, content] of images) {
  const secs = (content * 8) / mbps;                   // MB -> Mbit -> সেকেন্ড
  console.log(
    name.padEnd(30),
    String(disk).padStart(6),
    String(content).padStart(6),
    (content / naive).toFixed(2).padStart(7),
    secs.toFixed(1).padStart(11),
    (content * servers).toFixed(0).padStart(9) + " MB"
  );
}
const app = 97.8 - 85.7;
console.log(`web multi-stage minus base = ${app.toFixed(1)} MB of your own layers`);

৩ · .dockerignore — ভুল জিনিস image-এ ঢোকার আগেই থামান

docker build .-এর শেষের বিন্দুটি build context: এই ফোল্ডারের সব ফাইল builder-এর কাছে পাঠানো হয়, আর COPY . . সেখান থেকেই কপি করে। .dockerignore ফাইল বলে দেয় কোনগুলো পাঠানো হবে না। ল্যাবে web ফোল্ডারে একটি নকল .env রাখা হয়েছিল, যেমন অনেকের project-এ থাকে:

DATABASE_URL=postgresql://shop:example-secret@db:5432/shop
PAYMENT_SECRET=example-secret

তারপর naive Dockerfile .dockerignore ছাড়া build করা হলো। সত্যিকারের run:

$ docker build -f Dockerfile.naive -t bz80-web:naive .
#4 transferring context: 141.77MB 9.5s
#4 transferring context: 289.79MB 19.8s
#4 transferring context: 375.06MB 25.1s done
…
#7 57.75 added 3 packages, removed 4 packages, and audited 29 packages in 58s

$ docker run --rm bz80-web:naive cat /app/.env
DATABASE_URL=postgresql://shop:example-secret@db:5432/shop
PAYMENT_SECRET=example-secret

দুটি ক্ষতি একসাথে। এক, ৩৭৫MB context, কারণ আপনার কম্পিউটারের node_modules পুরোটা পাঠানো হয়েছে; শুধু পাঠাতেই ২৫ সেকেন্ড। লক্ষ করুন added 3 packages, removed 4 packages: ল্যাবের node_modules Windows-এ install করা, তাতে Windows-এর native binary ছিল; Linux container-এ npm সেগুলো সরিয়ে Linux-এর package বসিয়েছে। সবসময় এমন ভাগ্য হয় না; অন্য মেশিনের node_modules কপি হলে ভুল platform-এর binary নিয়ে crash খুব পরিচিত সমস্যা। দুই, .env image-এর ভেতরে। এই image কোনো registry-তে গেলে যিনিই image টানতে পারেন, তিনিই secret পড়তে পারেন; পরের layer-এ rm .env দিলেও আগের layer-এ তা থেকে যায়। এখন .dockerignore-সহ একই ফোল্ডারে multi-stage build:

node_modules
.next
.env*
!.env.example
Dockerfile*
.dockerignore
npm-debug.log*
.git

#5 [internal] load .dockerignore
#5 transferring context: 125B done
#6 [internal] load build context
#6 transferring context: 36.14kB done

$ docker run --rm bz80-web:multi sh -c "ls -la /app/.env"
ls: cannot access '/app/.env': No such file or directory

৩৭৫MB থেকে ৩৬KB, আর .env নেই। Secret তাহলে container-এ পৌঁছায় কীভাবে? চালানোর সময় environment variable হিসেবে, বা secret manager থেকে; build-এ কোনো secret লাগলে BuildKit-এর --mount=type=secret, যা layer-এ থাকে না। বিস্তারিত পর্ব ৭৮-এ আর Cloud কোর্সের Dockerfile পর্বে। নিয়মগুলো কীভাবে মেলে, একটি ছোট মডেলে দেখুন:

#!/bin/bash
# শিক্ষার মডেল: .dockerignore-এর মতো মেলানো (আসল নিয়মের সরল রূপ)
# নিয়ম: উপর থেকে নিচে পড়া হয়, শেষে যে pattern মেলে সেটিই জেতে; ! মানে আবার রাখা হবে
patterns=("node_modules" ".next" ".env*" "!.env.example" "Dockerfile*" ".git")
files=(app/page.tsx package.json package-lock.json public/robots.txt
       .env .env.local .env.example node_modules/next/package.json
       .next/cache/webpack.pack Dockerfile .git/HEAD)

ignored() {                       # 0 = বাদ যাবে, 1 = পাঠানো হবে
  local f=$1 res=1 p neg
  for p in "${patterns[@]}"; do
    neg=0
    if [[ $p == !* ]]; then neg=1; p=${p#!}; fi
    if [[ $f == $p || $f == $p/* ]]; then res=$neg; fi
  done
  return $res
}

sent=0; skipped=0
for f in "${files[@]}"; do
  if ignored "$f"; then echo "SKIP  $f"; skipped=$((skipped+1))
  else echo "SEND  $f"; sent=$((sent+1)); fi
done
echo "context: $sent sent, $skipped skipped"

৪ · Layer cache — কোড বদল বনাম dependency বদল

Dockerfile-এর প্রতিটি নির্দেশ একটি cache-যোগ্য ধাপ। BuildKit দেখে: নির্দেশ একই, আগের ধাপ একই, আর COPY হলে কপি হওয়া ফাইলের বিষয়বস্তু একই কি না। সব মিললে আগের ফল ব্যবহার করে (CACHED); একটি ধাপ বদলালে সেই ধাপ আর তার পরের সব ধাপ আবার চলে। তত্ত্বটি Docker image পর্বে আছে; এখানে বাজারঘরে মাপা যাক।

ল্যাবে একই web প্রজেক্টে পাঁচটি build চালানো হলো (একটি local run): কিছু না বদলে, app/page.tsx-এর একটি শব্দ বদলে, zod package যোগ করে (package-lock.json বদল), আর তুলনার জন্য একটি “ভুল ক্রমের” Dockerfile, যেখানে COPY . . আগে, npm ci পরে।

সত্যিকারের log-এর দুটি টুকরো, কোড বদলের পরে:

# তিন ধাপের Dockerfile, app/page.tsx বদলের পরে
#8 [deps 3/4] COPY package.json package-lock.json ./   CACHED
#9 [deps 4/4] RUN npm ci                               CACHED
#12 [build 4/5] COPY . .                               DONE 0.0s
#13 [build 5/5] RUN npm run build                      DONE 4.1s

# ভুল ক্রমের Dockerfile, একই বদলের পরে
#6 [3/5] COPY . .                                      DONE 0.1s
#7 [4/5] RUN npm ci                                    DONE 33.2s
#8 [5/5] RUN npm run build                             DONE 3.7s

দিনে বিশবার build করলে পার্থক্য প্রায় ২০ × ৪২ = ৮৪০ সেকেন্ড, অর্থাৎ ১৪ মিনিট, শুধু অপেক্ষায়। CI-তে প্রতি push-এ এই খরচ আরও বড়, যদি সেখানে cache রাখা হয় (pipeline-এর নকশা)। নিচের মডেলে নিয়মটি কোডে লেখা:

// শিক্ষার মডেল: BuildKit কোন ধাপ আবার চালাবে (আসল BuildKit নয়)
// সেকেন্ডগুলো এই পর্বের ল্যাবের একটি local run থেকে নেওয়া
const good = [
  { st: "deps",   id: "copy-pkg",   reads: ["package.json", "package-lock.json"] },
  { st: "deps",   id: "npm-ci",     sec: 33.3 },
  { st: "build",  id: "from-deps",  from: "deps" },
  { st: "build",  id: "copy-src",   reads: ["*"] },
  { st: "build",  id: "next-build", sec: 4.1 },
  { st: "runner", id: "from-build", from: "build" },
];
const bad = [
  { st: "one", id: "copy-src",   reads: ["*"] },
  { st: "one", id: "npm-ci",     sec: 33.3 },
  { st: "one", id: "next-build", sec: 4.1 },
];
function plan(name, steps, changed) {
  const dirty = {}; let sec = 0; const ran = [];
  for (const s of steps) {
    let d = dirty[s.st] || (s.from ? !!dirty[s.from] : false);
    if (s.reads && s.reads.some((f) => (f === "*" ? changed.length > 0 : changed.includes(f)))) d = true;
    dirty[s.st] = d;
    if (d) { sec += s.sec || 0; ran.push(s.id); }
  }
  const cached = steps.length - ran.length;
  console.log(`${name.padEnd(24)} ~${sec.toFixed(1).padStart(4)}s  cached ${cached}, rerun: ${ran.join(", ") || "-"}`);
}
plan("good: no change", good, []);
plan("good: app/page.tsx", good, ["app/page.tsx"]);
plan("good: package-lock.json", good, ["package-lock.json"]);
plan("bad:  app/page.tsx", bad, ["app/page.tsx"]);

৫ · Prisma container-এ — generate, engine, OpenSSL আর migrate job

api-র Dockerfile-এর গঠন web-এর মতোই, সাথে একটি বাড়তি ধাপ। prisma generate build-এর সময় চলে (npm run build = prisma generate && tsc), আর migrate-এর জন্য আলাদা একটি target:

# syntax=docker/dockerfile:1
FROM node:26-slim AS deps
WORKDIR /app
COPY package.json package-lock.json ./
RUN npm ci

FROM node:26-slim AS build
WORKDIR /app
COPY --from=deps /app/node_modules ./node_modules
COPY . .
RUN npm run build

FROM node:26-slim AS prod-deps
WORKDIR /app
COPY package.json package-lock.json ./
RUN npm ci --omit=dev --omit=optional

# one-off job: prisma migrate deploy (has the prisma CLI)
FROM build AS migrate
USER node
CMD ["npx", "prisma", "migrate", "deploy"]

FROM node:26-slim AS runner
WORKDIR /app
ENV NODE_ENV=production
COPY --from=prod-deps /app/node_modules ./node_modules
COPY --from=build /app/dist ./dist
COPY package.json ./
USER node
EXPOSE 4000
CMD ["node", "dist/server.js"]

runner শেষে রাখা জরুরি: --target না দিলে docker build শেষ ধাপটিই বানায়। এই Dockerfile তিনটি সত্যিকারের সমস্যা পেরিয়ে এখানে পৌঁছেছে।

সমস্যা ১: build-এ DATABASE_URL নেই

পর্ব ৪০-এর prisma.config.ts-এ লেখা ছিল url: env('DATABASE_URL'). Container-এর build-এ কোনো database নেই, থাকা উচিতও নয়। সত্যিকারের build:

#13 3.601 Failed to load config file "/app" as a TypeScript/JavaScript module. Error: PrismaConfigEnvError: Cannot resolve environment variable: DATABASE_URL.
ERROR: failed to build: failed to solve: process "/bin/sh -c npm run build" did not complete successfully: exit code: 1

Prisma-র v7 config reference বলে, env() helper variable না পেলে error দেয়; যেখানে শুধু generate চলে, সেখানে সরাসরি process.env পড়তে বলে। ঠিক করা config:

import { defineConfig } from 'prisma/config';

export default defineConfig({
  schema: 'prisma/schema.prisma',
  migrations: { path: 'prisma/migrations', seed: 'node dist/seed.js' },
  datasource: {
    // build-এ (prisma generate) DATABASE_URL থাকে না; migrate deploy-এর সময় থাকে
    url: process.env.DATABASE_URL ?? '',
  },
});

ভুল সমাধান হতো build-এ ENV DATABASE_URL=... লিখে দেওয়া: তাতে সত্যিকারের password image-এর metadata-য় থেকে যায়।

সমস্যা ২: production image-এ Prisma CLI ঢুকে পড়ে

প্রথম চেষ্টায় prod-deps ধাপে ছিল শুধু npm ci --omit=dev. Image হলো 841MB, যেখানে node_modules একাই ৩৭০M, তার মধ্যে @prisma/* ১৬৭M আর prisma CLI ৪১M. কারণ খুঁজতে lockfile দেখা হলো: @prisma/client prisma-কে optional peer dependency হিসেবে ঘোষণা করে, আর আমাদের package.json-এ prisma devDependency. npm এমন package-কে lockfile-এ devOptional চিহ্ন দেয়, আর তা বাদ যায় শুধু dev আর optional দুটোই বাদ দিলে। --omit=dev --omit=optional দেওয়ার পরে:

$ docker image ls      # কলাম ছোট করা
bz80-api:1   (--omit=dev)            841MB   187MB
bz80-api:3   (--omit=dev,optional)   481MB   116MB
$ docker run --rm bz80-api:3 sh -c "du -sh /app/node_modules; ls /app/node_modules/@prisma"
94M	/app/node_modules
adapter-pg  client  client-runtime-utils  debug  driver-adapter-utils

অংশ ২-এর টেবিলে আর পরের তুলনায় এই image-এর মাপ লেখা আছে 483MB আর 117MB, ওপরের এই run-এ এসেছে 481MB আর 116MB. দুটিই আলাদা build-এর মাপ; একই নির্দেশেও দুই build-এর মাপ কয়েক MB আলাদা হতে পারে, তাই হিসাবে মোটা দাগের তুলনাটিই ধরুন।

লক্ষ করুন, runner-এ @prisma/engines নেই, তবু api database-এ query চালিয়েছে। লেখার সময়ের Prisma 7-এ prisma-client generator আর driver adapter (@prisma/adapter-pg) ব্যবহার করলে client-এর জন্য আলাদা Rust query engine binary লাগে না, query তৈরি হয় JavaScript আর WebAssembly-তে। Engine binary এখন লাগে মূলত migrate-এর schema engine-এর জন্য, আর সেটি আছে migrate image-এ।

সমস্যা ৩: Alpine, Debian slim আর OpenSSL

পুরোনো Prisma version-এ Alpine-এ OpenSSL না পাওয়ার error খুব পরিচিত ছিল, কারণ Prisma-র engine binary নির্দিষ্ট OS, C library আর OpenSSL version-এর জন্য বানানো। একই Dockerfile শুধু node:26-slim-এর জায়গায় node:26-alpine দিয়ে চালানো হলো। সত্যিকারের ফল, একটি নতুন database-এ:

$ docker run --rm --network bz80_default -e DATABASE_URL=… bz80-api-migrate:alpine
Applying migration `20261103090000_init`
All migrations have been successfully applied.

$ ls /app/node_modules/@prisma/engines/          # slim image-এ
schema-engine-debian-openssl-3.0.x
$ ls /app/node_modules/@prisma/engines/          # alpine image-এ
schema-engine-linux-musl-openssl-3.0.x

কোনো error নেই। Prisma build-এর সময় platform চিনে ঠিক binary এনেছে: Debian-এ glibc-র জন্য, Alpine-এ musl-এর জন্য, আর দুটো image-এই libssl.so.3 আছে। কিন্তু base image ছোট করতে গিয়ে কেউ libssl সরিয়ে দিলে কী হয়? ল্যাবে Alpine image থেকে libssl মুছে আরেকটি নতুন database-এ চালানো হলো:

prisma:warn Prisma failed to detect the libssl/openssl version to use, and may not work as expected. Defaulting to "openssl-1.1.x".
Please manually install OpenSSL and try installing Prisma again.
Error: Can't write to /app/node_modules/@prisma/engines please make sure you install "prisma" with the right permissions.

দুটি শিক্ষা এক error-এ। প্রথমত, OpenSSL না পেলে Prisma পুরোনো 1.1.x ধরে নিয়ে অন্য binary নামাতে চায়। দ্বিতীয়ত, সেটি নামাতে চায় চালানোর সময়, কিন্তু container চলছে non-root node user-এ, আর node_modules root-এর, তাই লেখা যায় না। এটি আসলে ভালো খবর: production container চালু হওয়ার সময় internet থেকে binary নামানো উচিতই নয়। নিয়ম: engine আর generate build-এর সময়, যে base image-এ চলবে সেই base image-এই।

Migrate: প্রতিটি start-এ নয়, deploy-এর আগে একবার

অনেক Dockerfile-এ দেখা যায় CMD npx prisma migrate deploy && node server.js. একটি container-এ চলে, কিন্তু চারটি api container একসাথে চালু হলে চারটিই migrate চালাতে চায়; Prisma Migrate PostgreSQL-এ lock নিয়ে একসাথে চলা আটকানোর চেষ্টা করে বলে জানা যায়, তবু প্রতিটি start ধীর হয়, app-এর image-এ CLI রাখতে হয়, আর migrate ব্যর্থ হলে app crash loop-এ পড়ে। ভালো পথ: migrate একটি one-off job. Compose-এ সেটি migrate service, CI/CD-তে deploy-এর আগের একটি ধাপ (পর্ব ৮১), Kubernetes-এ একটি Job. Compose-এ দ্বিতীয়বার up করলে সত্যিকারের log:

migrate-1  | 1 migration found in prisma/migrations
migrate-1  | No pending migrations to apply.

Migrate চালানোর অধিকারও আলাদা হতে পারে: migrate job-এর database user টেবিল বানাতে পারে, app-এর user শুধু ডেটা পড়া-লেখা। ধ্বংসাত্মক বদল কীভাবে কয়েক ধাপে করতে হয় (expand and contract), সেটি পর্ব ৪০-এ আছে।

৬ · NEXT_PUBLIC_ — build-এর সময়েই বসে যায়

Web-এর Dockerfile-এ ARG NEXT_PUBLIC_SHOP_NAME কেন? কারণ NEXT_PUBLIC_ দিয়ে শুরু variable-এর মান Next.js next build-এর সময় JavaScript-এর ভেতরে লিখে দেয়। Container চালানোর সময় অন্য মান দিলে কী হয়, ল্যাবে দেখা হলো। Image build হয়েছিল --build-arg NEXT_PUBLIC_SHOP_NAME="Bazarghar Dhaka" দিয়ে; চালানো হলো অন্য মান দিয়ে:

$ docker run -d --name bz80-envtest -e NEXT_PUBLIC_SHOP_NAME="Bazarghar Chattogram" … bz80-web:dev
$ curl -s http://127.0.0.1:18081/ | grep shop
<p id="shop">Shop: Bazarghar Dhaka</p>
$ docker exec bz80-envtest sh -c 'echo "env in container: $NEXT_PUBLIC_SHOP_NAME"; grep -rl "Bazarghar Dhaka" /app/.next'
env in container: Bazarghar Chattogram
/app/.next/server/chunks/ssr/app_banner_tsx_0iyt50sn7omn_._.js
/app/.next/static/chunks/0oz8u40l6mx_i.js

Container-এর environment-এ “Chattogram”, অথচ পাতায় “Dhaka”, কারণ মানটি server-এর SSR chunk আর browser-এর static chunk দুই জায়গাতেই লেখা হয়ে গেছে। এর দুটি ফল। এক, staging আর production-এ আলাদা NEXT_PUBLIC_ মান লাগলে দুটি আলাদা image build করতে হয়, অথবা মানটি runtime-এ server থেকে পড়তে হয়। দুই, NEXT_PUBLIC_-এ কখনো secret নয়, কারণ সেটি সবার browser-এ যায়। অন্যদিকে API_URL (NEXT_PUBLIC_ ছাড়া) server component চালানোর সময় পড়ে, তাই compose-এ http://api:4000 দিলে সেটিই কাজ করেছে। পুরো আলোচনা, আর “একটি build, অনেক পরিবেশ” কীভাবে করবেন, পর্ব ৭৮-এ।

৭ · Compose দিয়ে পুরো stack — health check, ক্রম, volume আর seed

সাতটি container হাতে একটি একটি করে চালানো ক্লান্তিকর আর ভুলপ্রবণ। Docker Compose একটি YAML ফাইলে পুরো stack লেখে। Local development আর CI-র জন্য এটি দারুণ; production-এ একটি VPS-এ ছোট অ্যাপের জন্যও অনেকে ব্যবহার করেন। Compose-এর সাধারণ কমান্ড Cloud কোর্সের Compose পর্বে। বাজারঘরের ফাইল (কিছুটা ছোট করা):

name: bz80
x-db-url: &db-url postgresql://shop:example-secret@postgres:5432/bazarghar

services:
  postgres:
    image: postgres:18-alpine
    environment: { POSTGRES_USER: shop, POSTGRES_PASSWORD: example-secret, POSTGRES_DB: bazarghar }
    volumes: [ "pgdata:/var/lib/postgresql" ]
    healthcheck:
      test: ["CMD-SHELL", "pg_isready -U shop -d bazarghar"]
      interval: 3s
      retries: 10
  redis:
    image: redis:8-alpine
    volumes: [ "redisdata:/data" ]
    healthcheck: { test: ["CMD", "redis-cli", "ping"], interval: 3s, retries: 10 }
  migrate:
    build: { context: ./api, target: migrate }
    environment: { DATABASE_URL: *db-url }
    depends_on: { postgres: { condition: service_healthy } }
  seed:
    build: ./api
    command: ["node", "dist/seed.js"]
    environment: { DATABASE_URL: *db-url }
    depends_on: { migrate: { condition: service_completed_successfully } }
  api:
    build: ./api
    init: true
    stop_grace_period: 10s
    environment: { DATABASE_URL: *db-url, REDIS_URL: "redis://redis:6379" }
    ports: [ "127.0.0.1:18040:4000" ]
    depends_on:
      seed: { condition: service_completed_successfully }
      redis: { condition: service_healthy }
    healthcheck:
      test: ["CMD", "node", "-e", "fetch('http://127.0.0.1:4000/healthz').then(r=>process.exit(r.ok?0:1)).catch(()=>process.exit(1))"]
      interval: 5s
      start_period: 10s
    deploy: { resources: { limits: { cpus: "0.50", memory: 256M } } }
  worker:
    build: ./api
    init: true
    command: ["node", "dist/worker.js"]
    depends_on:
      migrate: { condition: service_completed_successfully }
      redis: { condition: service_healthy }
  web:
    build: { context: ./web, args: { NEXT_PUBLIC_SHOP_NAME: "Bazarghar Dhaka" } }
    init: true
    environment: { API_URL: "http://api:4000" }
    ports: [ "127.0.0.1:18080:3000" ]
    depends_on: { api: { condition: service_healthy } }

volumes:
  pgdata:
  redisdata:

কয়েকটি সিদ্ধান্ত ব্যাখ্যা করি। depends_on-এর সাধারণ রূপ শুধু “আগে চালু করা” বোঝায়, “তৈরি হলে” নয়। PostgreSQL-এর process চালু হওয়া আর সংযোগ নিতে পারার মধ্যে কয়েক সেকেন্ড ফাঁক থাকে; condition: service_healthy সেই ফাঁক ঢাকে, কারণ তখন compose health check সফল হওয়া পর্যন্ত অপেক্ষা করে। service_completed_successfully মানে “ওই container exit 0 দিয়ে শেষ হলে”, যা migrate আর seed-এর জন্য ঠিক। Slim image-এ curl নেই, তাই health check Node-এর নিজের fetch দিয়ে, আর /healthz শুধু “process বেঁচে আছে” নয়, database-এ SELECT 1-ও চালায় (পর্ব ৩১-এর liveness আর readiness ভাবনা)। Port শুধু 127.0.0.1-এ খোলা, যাতে অফিসের network থেকে কেউ dev database বা API-তে না ঢোকেন। আর named volume pgdata: container মুছে আবার বানালেও ডেটা থাকে; docker compose down -v দিলে তবেই মোছে। Password এখানে স্পষ্ট নকল (example-secret); আসল প্রজেক্টে compose ফাইলে নয়, .env বা secret থেকে আসবে।

 Network bz80_default Created
 Volume bz80_pgdata Created
 Volume bz80_redisdata Created
 …
 Container bz80-postgres-1 Started
 Container bz80-redis-1 Started
 Container bz80-postgres-1 Waiting

 Container bz80-postgres-1 Healthy
 Container bz80-migrate-1 Starting
 Container bz80-migrate-1 Started
 Container bz80-redis-1 Healthy

migrate-1 | 1 migration found in prisma/migrations
migrate-1 | Applying migration `20261103090000_init`
migrate-1 | All migrations have been successfully applied.
 Container bz80-migrate-1 Exited
 Container bz80-worker-1 Starting
 Container bz80-seed-1 Starting

seed-1   | seed: 3 products upserted
worker-1 | worker ready, queue=orders
 Container bz80-seed-1 Exited
 Container bz80-api-1 Starting

api-1    | api listening on 4000
 Container bz80-api-1 Waiting
 Container bz80-api-1 Healthy   ← /healthz: SELECT 1
 Container bz80-web-1 Starting

SERVICE    STATUS
api        Up 14 seconds (healthy)
migrate    Exited (0) 15 seconds ago
postgres   Up 23 seconds (healthy)
redis      Up 23 seconds (healthy)
seed       Exited (0) 14 seconds ago
web        Up 5 seconds (healthy)
worker     Up 14 seconds

এবার stack-এর ভেতর দিয়ে একটি সত্যিকারের অনুরোধ: browser থেকে web, web-এর server component থেকে api, api থেকে PostgreSQL; তারপর একটি order, যা Redis-এর queue হয়ে worker-এ যায়।

$ curl -s http://127.0.0.1:18080/
<p id="shop">Shop: Bazarghar Dhaka</p><ul><li>Miniket Rice 5kg: 420 taka (stock 40)</li><li>Masur Dal 1kg: 135 taka (stock 60)</li><li>Tea 400g: 260 taka (stock 25)</li></ul>

$ curl -s -i -X POST http://127.0.0.1:18040/orders -H 'content-type: application/json' -d '{"productId":2,"qty":3}'
HTTP/1.1 201 Created
{"id":1,"productId":2,"qty":3,"status":"pending","createdAt":"2026-11-03T11:37:44.782Z"}

$ docker compose logs worker
worker-1  | job 1: order 1 confirmed

$ docker compose exec -T postgres psql -U shop -d bazarghar -c 'SELECT id, "productId", qty, status FROM "Order";'
 id | productId | qty |  status
----+-----------+-----+-----------
  1 |         2 |   3 | confirmed

$ curl … -d '{"productId":2,"qty":99}'      # qty-র সীমা 1-10
400

Order pending হিসেবে তৈরি হয়ে 201 ফিরেছে, তারপর worker সেটিকে confirmed করেছে: পর্ব ৬২-এর producer আর worker এখন আলাদা container-এ। কেউ চাইলে docker compose up --scale worker=3 দিয়ে worker বাড়াতে পারেন, api না ছুঁয়েই।

একটি সত্যিকারের ব্যর্থতা: “Healthy” বলল, কিন্তু worker মরে গেল

প্রথম চেষ্টায় সব service “Healthy” দেখাল, অথচ কয়েক সেকেন্ড পরে:

 Container bz80-worker-1 Healthy
SERVICE    STATUS
worker     Exited (137) 1 second ago

worker-1  | Error: BullMQ could not load the optional 'ioredis' package. Install it with `npm install ioredis`, or provide a different Redis client instance (e.g. node-redis) via the connection option. In a native ESM environment, pass an already-constructed client instance instead of connection options.
worker-1  |     at new Worker (/app/node_modules/bullmq/dist/cjs/classes/worker.js:43:9)

$ docker inspect bz80-worker-1 --format "{{.State.OOMKilled}} {{.State.ExitCode}}"
true 137

তিনটি শিক্ষা। এক, BullMQ 6 ioredis-কে optional peer ঘোষণা করে, তাই সেটি dependencies-এ নিজে লিখতে হয়; error বার্তা ঠিক সেটিই বলেছে, আর ESM-এ একটি তৈরি client দিতে বলেছে। সমাধান: ioredis 6.0.0 যোগ করে new Redis(url, { maxRetriesPerRequest: null }) পাঠানো। দুই, error-এর ধারায় memory বেড়ে ২৫৬MB সীমা ছাড়িয়েছে, kernel process মেরেছে (OOMKilled true, exit 137): resource limit কাজ করেছে, পুরো মেশিন বাঁচিয়েছে। তিন, health check ছাড়া service-এর ক্ষেত্রে compose-এর “Healthy” মানে শুধু “চালু হয়েছিল”। Worker-এর জন্য heartbeat ফাইল বা queue-র সংযোগ যাচাই করা health check, আর restart: unless-stopped নীতি ভাবার মতো।

Compose-এর এই শর্তগুলো থেকে কে কখন চালু হবে, তা হিসাব করা যায়। নিচের মডেলে প্রতিটি service কত সেকেন্ডে তৈরি হয়, তা ধরে নেওয়া সংখ্যা:

// শিক্ষার মডেল: compose-এর depends_on আর condition থেকে চালুর সময় (আসল compose নয়)
// ready = চালুর কত সেকেন্ড পরে healthy বা কাজ শেষ (ধরে নেওয়া সংখ্যা)
const svc = {
  postgres: { ready: 4, deps: {} },
  redis:    { ready: 2, deps: {} },
  migrate:  { ready: 3, exit: 0, deps: { postgres: "service_healthy" } },
  seed:     { ready: 2, exit: 0, deps: { migrate: "service_completed_successfully" } },
  worker:   { ready: 1, deps: { migrate: "service_completed_successfully", redis: "service_healthy" } },
  api:      { ready: 5, deps: { seed: "service_completed_successfully", redis: "service_healthy" } },
  web:      { ready: 3, deps: { api: "service_healthy" } },
};
const memo = {};
function startAt(name, path = []) {
  if (path.includes(name)) throw new Error("cycle: " + [...path, name].join(" -> "));
  if (name in memo) return memo[name];
  let t = 0;
  for (const [dep, cond] of Object.entries(svc[name].deps)) {
    const s = startAt(dep, [...path, name]);
    if (s === null) return (memo[name] = null);           // dependency failed
    if (cond === "service_completed_successfully" && svc[dep].exit !== 0) return (memo[name] = null);
    t = Math.max(t, cond === "service_started" ? s : s + svc[dep].ready);
  }
  return (memo[name] = t);
}
function show(title) {
  for (const k in memo) delete memo[k];
  console.log("--", title);
  const rows = Object.keys(svc).map((n) => [n, startAt(n)]);
  rows.sort((a, b) => (a[1] ?? 99) - (b[1] ?? 99));
  for (const [n, t] of rows) console.log(n.padEnd(9), t === null ? "never started (dependency failed)" : `start t=${t}s`);
}
show("all good");
svc.migrate.exit = 1;
show("migrate exits 1");

৮ · SIGTERM, PID 1 আর init — থামার সময় অর্ডার না হারানো

নতুন version deploy, docker compose down বা server-এর রক্ষণাবেক্ষণ: সব ক্ষেত্রেই Docker প্রথমে container-এর প্রধান process-কে SIGTERM পাঠায়, তারপর সময়সীমা (Docker-এ সাধারণত ১০ সেকেন্ড) পেরোলে SIGKILL. পর্ব ৩১-এ graceful shutdown-এর কোড শিখেছেন: নতুন সংযোগ বন্ধ, চলমান অনুরোধ শেষ, তারপর exit. Container-এ একটি বাড়তি মোড় আছে: PID 1.

Container-এর ভেতরে প্রথম process-এর PID 1, যেমন একটি পুরো Linux-এ init. Linux kernel PID 1-কে বিশেষ সুরক্ষা দেয়: যে signal-এর জন্য process নিজে কোনো handler বসায়নি, সেটি PID 1-এ পৌঁছালে ডিফল্ট আচরণ (মরে যাওয়া) ঘটে না। Node নিজে থেকে SIGTERM-এর handler বসায় না। ফলে Node যখন PID 1 আর আপনার কোডে handler নেই, SIGTERM কিছুই করে না। Init process (যেমন tini) PID 1 হয়ে বসে, signal Node-এর কাছে পাঠিয়ে দেয়, আর মরে যাওয়া child process-গুলোও পরিষ্কার করে। Docker-এ --init, compose-এ init: true এটি যোগ করে।

ল্যাবে একটি ছোট server বানানো হলো, যার /slow উত্তর দিতে ৩ সেকেন্ড লাগে, যেন একটি order সেভ হচ্ছে। একটি অনুরোধ পাঠিয়ে ১ সেকেন্ড পরে docker stop, চারভাবে। সময়সীমা স্পষ্ট করে --stop-timeout 10 দেওয়া হয়েছিল। সত্যিকারের run:

import http from 'node:http';

const server = http.createServer((req, res) => {
  if (req.url === '/slow') {               // একটি order সেভ হতে ৩ সেকেন্ড লাগে
    setTimeout(() => res.end('order saved\n'), 3000);
    return;
  }
  res.end('ok\n');
});
server.listen(3000, () => console.log(`pid ${process.pid} listening`));

if (process.env.GRACEFUL === '1') {
  process.on('SIGTERM', () => {
    console.log('SIGTERM: no new connections, finishing in-flight');
    server.close(() => { console.log('closed cleanly'); process.exit(0); });
  });
}

t=0.0  curl /slow           (উত্তর আসবে t≈3.0-এ)
t=1.0  docker stop          → PID 1-এ SIGTERM
       ১০ সেকেন্ডে না থামলে → SIGKILL
মাপা হয়: client কী পেল, stop কত সময় নিল, exit code

log: pid 1 listening
client: rc=0 reply='order saved' after 3.3s
docker stop took 11.3s
exit code: 137

log: pid 7 listening
client: rc=52 reply='curl: (52) Empty reply from server' after 1.2s
docker stop took 0.5s
exit code: 143

log: pid 7 listening
log: SIGTERM: no new connections, finishing in-flight
log: closed cleanly
client: rc=0 reply='order saved' after 3.0s
docker stop took 2.3s
exit code: 0

log: pid 1 listening
log: SIGTERM: no new connections, finishing in-flight
log: closed cleanly
client: rc=0 reply='order saved' after 3.0s
docker stop took 2.4s
exit code: 0

বাজারঘরের api আর worker-এ handler আছে, আর compose-এ init: true. docker compose stop api worker-এর সত্যিকারের log:

api-1     | SIGTERM received, closing server
api-1     | api stopped cleanly
worker-1  | SIGTERM received, finishing current job
worker-1  | worker stopped cleanly

৯ · নিরাপত্তা, সীমা আর পরের গন্তব্য — scan, digest, limit, registry

ছোট base image মানে কম ঝুঁকি

Image-এ যত বেশি package, তত বেশি জানা দুর্বলতা (CVE) থাকার সম্ভাবনা। Vulnerability scanner image-এর package-এর তালিকা মিলিয়ে দেখে কোনগুলোর জানা দুর্বলতা আছে। ল্যাবে Trivy 0.76.1 (Aqua Security-র open-source scanner) চারটি image-এ চালানো হলো; binary-র SHA-256 প্রকাশিত checksum-এর সাথে মিলিয়ে নেওয়া হয়েছিল, কারণ scanner নিজেও supply chain-এর অংশ। Docker Scout-ও একটি পথ, কিন্তু তার পূর্ণ বিশ্লেষণে সাধারণত Docker account-এ login লাগে, আর এই ল্যাবে কোনো account-এ login না করার নিয়ম ছিল, তাই চালানো হয়নি।

সংখ্যাগুলো পড়তে বিচার লাগে। Slim image-এর ৪৪টি OS-স্তরের HIGH-এর একটিরও লেখার সময় Debian-এ fix ছিল না (util-linux, ncurses, perl-base-এর মতো package; বেশিরভাগই আমাদের app কখনো চালায় না)। বাকি ৬টি HIGH আমাদের কোডে নয়, Node.js runtime-এর ভেতরে বসানো undici আর brace-expansion-এ, যার সমাধান নতুন Node patch-এর base image. সত্যিকারের output-এর একটি অংশ (সময়ের ছাপ বাদ, টেবিলের প্রস্থ ছোট করা):

$ trivy image --scanners vuln --severity HIGH,CRITICAL bz80-web:dev
INFO	Detected OS	family="debian" version="13.7"
INFO	[debian] Detecting vulnerabilities...	os_version="13" pkg_num=80
INFO	[node-pkg] Detecting vulnerabilities...
│ bz80-web:dev (debian 13.7)                    │  debian  │       44        │
│ app/node_modules/next/package.json            │ node-pkg │        0        │
│ app/node_modules/react-dom/package.json       │ node-pkg │        0        │
…

অর্থাৎ নিয়মিত কাজ দুটি: base image নিয়মিত হালনাগাদ করে আবার build, আর scan-এর ফল দেখে সিদ্ধান্ত (fix আছে, আমাদের পথে আসে, তাহলে আগে)। তালিকা থেকে সিদ্ধান্তে যাওয়ার পদ্ধতি Cloud কোর্সের registry আর supply chain পর্বে।

Digest দিয়ে pin, non-root, health check, limit

node:26-slim একটি tag, যা সময়ের সাথে নতুন image-এ সরে যায়। পুনরুৎপাদনযোগ্য build-এর জন্য digest দিয়ে pin করা যায়; ল্যাবের build log-এ যে digest দেখা গেছে:

FROM node:26-slim@sha256:e4db4c914bf8ad241bd24804fc25d272d89bad97e68cdc8a1414862790a02c39 AS deps

Digest pin করলে নিরাপত্তা patch আর নিজে থেকে আসে না, তাই Dependabot বা Renovate-এর মতো টুল দিয়ে pin হালনাগাদের pull request নেওয়া একটি প্রচলিত পথ। বাকি অভ্যাসগুলো এই পর্বেই সত্যিকারে যাচাই হয়েছে: whoami → node, image-এ .env নেই, প্রতিটি service-এর health check. আর deploy.resources.limits দেওয়া container-এর সত্যিকারের docker stats (সীমা ছাড়া সারিগুলো বাদ):

NAME              CPU %     MEM USAGE / LIMIT
bz80-api-1        0.01%     61.55MiB / 256MiB
bz80-web-1        0.01%     48.05MiB / 512MiB
bz80-worker-1     0.00%     34.53MiB / 256MiB

সীমা ঠিক করার সময় মনে রাখুন, Node-এর heap-এর একটি সীমা আছে, আর container-এর memory সীমা তার চেয়ে কম হলে kernel আগেই মেরে ফেলবে (exit 137, অংশ ৭-এর worker-এর মতো)। Memory আর CPU সীমার পুরো আচরণ container চালানোর পর্বে। আরও কঠোর হতে চাইলে read_only: true, cap_drop: [ALL] আর distroless-এর মতো আরও ছোট base image ভাবা যায়; প্রতিটির সাথে debug করার সুবিধা কিছুটা কমে।

Image এরপর কোথায় যায়

এই পর্বে কোনো image কোথাও push করা হয়নি। বাস্তবে পথটি সাধারণত এমন: CI image build আর scan করে, commit-এর hash দিয়ে tag দিয়ে একটি container registry-তে push করে (Docker Hub, GitHub Container Registry, বা cloud সেবাদাতার registry, উদাহরণ হিসেবে), তারপর যেখানে চলবে সেখানে নামায়। জায়গা হতে পারে নিজের VPS-এ docker compose, Dockerfile বুঝতে পারে এমন কোনো PaaS, বা Kubernetes. কোনটি কখন, খরচ আর সীমা কী, সেটি পর্ব ৮২-এ; pipeline-এর ধাপ পর্ব ৮১-এ।

১০ · AI-এর যুগে container-এ ফুল-স্ট্যাক

“আমার Next.js আর Express অ্যাপের জন্য Dockerfile লিখে দিন” বললে AI কয়েক সেকেন্ডে কিছু একটা দেবে, আর সেটি প্রায়ই চলবেও। সমস্যা হলো “চলে” আর “ঠিক” এক নয়। এই পর্বের প্রতিটি ফাঁদ AI-এর লেখা Dockerfile-এ নিয়মিত দেখা যায়:

AI-এর লেখা Dockerfile আর compose মেলানোর চেকলিস্ট

• Next.js, Prisma আর BullMQ-এর option নিজের version-এর official docs-এর সাথে মিলিয়েছি
• Image build করে docker image ls-এ আকার, আর whoami-তে non-root দেখেছি
• docker run --rm img ls -la /app-এ .env বা সোর্সের অপ্রয়োজনীয় ফাইল নেই
• কোড বদলে rebuild করে npm ci CACHED দেখেছি
• নতুন volume-এ docker compose up --wait চালিয়ে প্রতিটি service-এর log পড়েছি, শুধু “Healthy” দেখে থামিনি
• চলমান অনুরোধের মাঝে docker stop দিয়ে exit 0 আর পূর্ণ উত্তর পেয়েছি
• অপ্রয়োজনীয় নতুন package বা base image যোগ হয়নি; diff লাইন ধরে পড়েছি, আর একটি scanner চালিয়েছি