Environment আর secret — dev, staging আর production

১ · এক কোড, চার পরিবেশ

“বাজারঘর” এখন আর একজনের ল্যাপটপের প্রজেক্ট নয়। ক্রেতারা অর্ডার দেন, টাকা আসে payment gateway দিয়ে। এই অবস্থায় নতুন কোড সরাসরি ক্রেতার সামনে পাঠানো ঝুঁকির। তাই কোড কয়েকটি ধাপ পেরিয়ে যায়। প্রতিটি ধাপ একটি environment, বাংলায় পরিবেশ: কোড যেখানে চলে, তার সাথে তার নিজের database, নিজের config আর নিজের secret.

শেষ সারিটি খেয়াল করুন। Staging-এ NODE_ENV হয় production, staging নয়। NODE_ENV বলে “কোড কোন মোডে বানানো আর চালানো হচ্ছে”: optimization চালু কি না, development-এর সতর্কবার্তা আসবে কি না। আর “কোন পরিবেশে চলছি” সেটি আলাদা প্রশ্ন, যার জন্য নিজের একটি variable রাখা ভালো, যেমন APP_ENV=staging. Next.js-এর docs অনুযায়ী NODE_ENV-এর বৈধ মান শুধু production, development আর test. সত্যিকারের run-এ NODE_ENV=staging দিয়ে build চালালে Next.js 16.4.4 সাথে সাথে সতর্ক করল:

$ NODE_ENV=staging npx next build
⚠ You are using a non-standard "NODE_ENV" value in your environment. This creates inconsistencies in the project and is strongly advised against.
▲ Next.js 16.4.4 (Turbopack)
- Environments: .env.local, .env.production, .env

নিচের ছবিতে পুরো ব্যবস্থাটি দেখুন। মাঝের তীরটিই এই পর্বের মূল কথা: একটি build staging থেকে production-এ ওঠে, কিন্তু প্রতিটি পরিবেশ নিজের config আর database পায়।

Preview environment প্রতিটি pull request-এর জন্য আলাদা একটি URL দেয়, যাতে review-এর মানুষ কোড না নামিয়েই বদলটি চোখে দেখতে পারেন। এটি কীভাবে CI-এ বানানো হয়, তা পর্ব ৮১ (CI/CD) আর পর্ব ৮২ (কোথায় চালাবেন)-এর বিষয়। এখানে আমরা শুধু দেখব, প্রতিটি পরিবেশ তার config কোথা থেকে পায়।

২ · Parity আর drift — মহড়া কেন আসলের মতো হতে হয়

“আমার মেশিনে তো চলছিল!” কথাটি এত পরিচিত কারণ পরিবেশগুলো চুপচাপ আলাদা হয়ে যায়। পরিবেশগুলো কতটা কাছাকাছি, তার নাম parity. আর সময়ের সাথে যে অমিল জমে, তার নাম drift. Twelve-Factor App-এর দশম নীতি “Dev/prod parity” তিনটি ফাঁকের কথা বলে: সময়ের ফাঁক (কোড লেখা থেকে deploy পর্যন্ত দিন বা সপ্তাহ), মানুষের ফাঁক (যিনি লেখেন আর যিনি চালান আলাদা), আর টুলের ফাঁক (ল্যাপটপে SQLite, production-এ PostgreSQL ব্যবহার)।

পর্ব ৩১-এ (Log আর config) আপনি config-কে environment-এ রাখা, node --env-file আর Zod দিয়ে চালুর মুহূর্তে যাচাই দেখেছেন। সেখানে প্রশ্ন ছিল “মান আছে কি না, ঠিক ধরনের কি না”। একাধিক পরিবেশ এলে আরও দুটি প্রশ্ন যোগ হয়: এই মান কি এই পরিবেশের জন্য বৈধ? আর কোনো গোপন মান কি ভুল করে public নামে বসেছে? নিচের যাচাই এই দুটিও ধরে। এখানেও আসল environment ছোঁয়া হচ্ছে না; stagingEnv একটি সাধারণ নকল object.

// নকল config: আসল environment-এর জায়গায় সাধারণ object
const stagingEnv = {
  APP_ENV: "staging",
  DATABASE_URL: "postgresql://shop:x@db-prod.bazarghar.example/shop",
  PAYMENT_SECRET: "short",
  NEXT_PUBLIC_API_URL: "https://staging-api.bazarghar.example",
  NEXT_PUBLIC_PAYMENT_KEY: "example-secret-oops",
};

function validateEnv(env) {
  const errors = [];
  const need = (key, ok, why) => { if (!ok(env[key])) errors.push(`${key}: ${why}`); };
  need("APP_ENV", (v) => ["local", "preview", "staging", "production"].includes(v), "unknown environment");
  need("DATABASE_URL", (v) => /^postgresql:\/\//.test(v ?? ""), "must be a postgresql:// URL");
  need("PAYMENT_SECRET", (v) => (v ?? "").length >= 24, "missing or shorter than 24 chars");
  need("NEXT_PUBLIC_API_URL", (v) => /^https?:\/\//.test(v ?? ""), "must be a URL");
  // public নামের ভেতরে secret-এর মতো শব্দ থাকলে সন্দেহ
  for (const key of Object.keys(env)) {
    if (key.startsWith("NEXT_PUBLIC_") && /SECRET|PASSWORD|PRIVATE|_KEY$/.test(key)) {
      errors.push(`${key}: looks like a secret but would be sent to the browser`);
    }
  }
  // staging কখনো production database-এ নয়
  if (env.APP_ENV !== "production" && /db-prod\./.test(env.DATABASE_URL ?? "")) {
    errors.push(`DATABASE_URL: ${env.APP_ENV} must not point at the production database`);
  }
  return errors;
}

const errors = validateEnv(stagingEnv);
if (errors.length > 0) {
  console.log(`Invalid environment (${errors.length} problems):`);
  for (const e of errors) console.log(`  - ${e}`);
  console.log("exit code 1: build stopped, nothing deployed");
}

৩ · Next.js 16-এ .env ফাইল আর load order

Next.js প্রজেক্টের মূল ফোল্ডারের .env* ফাইলগুলো নিজে থেকেই পড়ে process.env-এ বসায়; কোনো package লাগে না। ফাইল কয়েকটি, আর প্রতিটির কাজ আলাদা:

একই নাম কয়েক জায়গায় থাকলে কে জেতে? Next.js-এর docs অনুযায়ী খোঁজা হয় এই ক্রমে, আর প্রথম যেখানে পাওয়া যায় সেখানেই থামে:

অর্থাৎ shell বা হোস্টিং প্ল্যাটফর্ম যে মান দেয়, সেটি সব ফাইলের ওপরে। NODE_ENV=test হলে .env.local পড়া হয় না, যাতে সবার test একই মানে চলে। এই নিয়মগুলো আমরা সত্যিকারের একটি প্রজেক্টে যাচাই করেছি। লেখার সময়ের version: Next.js 16.4.4, React 19.3.1, Node 24.15.0. তিনটি ফাইলে নকল মান:

# .env — সবার জন্য ডিফল্ট
NEXT_PUBLIC_SHOP_NAME=Bazarghar
NEXT_PUBLIC_API_URL=http://127.0.0.1:4000
DATABASE_URL=postgresql://shop:example-pass@127.0.0.1:5432/bazarghar_dev
SUPPORT_PHONE=01700-000000

# .env.production — production build-এর ডিফল্ট
NEXT_PUBLIC_API_URL=https://api.bazarghar.example

# .env.local — শুধু এই যন্ত্রে, commit হয় না
NEXT_PUBLIC_SHOP_NAME=Bazarghar-Rahim-Laptop
PAYMENT_SECRET=example-secret-local-0123456789

একটি Client Component দুটি public মান আর একটি গোপন মান পড়ার চেষ্টা করে:

"use client";

export default function ShopBadge() {
  return (
    <p id="badge">
      shop={process.env.NEXT_PUBLIC_SHOP_NAME} api={process.env.NEXT_PUBLIC_API_URL}{" "}
      secret={String(process.env.PAYMENT_SECRET)}
    </p>
  );
}

সত্যিকারের run (ল্যাবের প্রজেক্ট ~/bazarghar):

$ npx next build
▲ Next.js 16.4.4 (Turbopack)
- Environments: .env.local, .env.production, .env
✓ Compiled successfully
…
Route (app)
┌ ƒ /
└ ○ /_not-found

$ grep -l 'Rahim-Laptop' .next/static/chunks/*.js
.next/static/chunks/2wz2_e59-gcq7.js
$ grep -o 'shop=","[^"]*"," api=","[^"]*"' .next/static/chunks/2wz2_e59-gcq7.js
shop=","Bazarghar-Rahim-Laptop"," api=","https://api.bazarghar.example"
$ grep -rl 'example-secret' .next/static | wc -l
0

দ্বিতীয় লাইনেই Next.js জানিয়ে দেয় কোন কোন ফাইল পড়া হলো। তারপর grep দেখাচ্ছে, browser-এ যাওয়া ফাইলে দুটি public মান লেখা হিসেবে বসে গেছে, আর secret কোথাও নেই। নিচের ধাপে একটি মানের পুরো যাত্রা দেখুন।

- Environments: .env.local, .env.production, .env
.env.development পড়া হয়নি: এটি build, dev নয়

NEXT_PUBLIC_SHOP_NAME
  .env.local      → Bazarghar-Rahim-Laptop
  .env            → Bazarghar (খোঁজাই হলো না)
NEXT_PUBLIC_API_URL
  .env.production → https://api.bazarghar.example
  .env            → http://127.0.0.1:4000

process.env.NEXT_PUBLIC_SHOP_NAME
  ↓
"Bazarghar-Rahim-Laptop"

String(t.default.env.PAYMENT_SECRET)
browser-এ এই lookup দেয় undefined
grep 'example-secret' .next/static → 0

NEXT_PUBLIC_SHOP_NAME=Bazarghar-Staging next start
served chunk: shop=","Bazarghar-Rahim-Laptop"

৪ · NEXT_PUBLIC_ build-এ জমে যায় — দুটি আসল ফাঁদ

NEXT_PUBLIC_ prefix কোনো সুরক্ষা নয়, বরং উল্টো: এটি একটি ঘোষণা যে “এই মান প্রকাশ্য, browser-এ পাঠানো যাবে”। Docs-এর ভাষায়, Next.js build-এর সময় মানটি browser-এ যাওয়া JavaScript bundle-এ “inline” করে, আর build-এর পরে এই variable বদলালে অ্যাপ আর সাড়া দেয় না। Vite-এর VITE_ নিয়ে একই কথা আপনি পর্ব ৫-এ দেখেছেন। এবার দুটি ফাঁদ, দুটিই ল্যাবের সত্যিকারের run-এ ধরা পড়েছে।

ফাঁদ ১: build-এর পরে মান বদলানো

একই build-কে staging মনে করে চালানো হলো, shell-এ নতুন দুটি মান দিয়ে। Page-টি একটি Server Component, যা connection() ডেকে নিশ্চিত করে যে এটি প্রতিটি request-এ চলবে:

import { connection } from "next/server";
import ShopBadge from "./ShopBadge";

export default async function Home() {
  await connection(); // request-এর সময় চলবে, build-এর সময় নয়
  const secretLength = (process.env.PAYMENT_SECRET ?? "").length;
  return (
    <main>
      <ShopBadge />
      <p id="server">
        server: support={process.env.SUPPORT_PHONE} shopOnServer={process.env.NEXT_PUBLIC_SHOP_NAME} secretLength={secretLength}
      </p>
    </main>
  );
}

$ NEXT_PUBLIC_SHOP_NAME=Bazarghar-Staging SUPPORT_PHONE=01800-111111 npx next start -H 127.0.0.1 -p 4178
▲ Next.js 16.4.4
✓ Ready in 125ms

$ curl -s http://127.0.0.1:4178/ | grep -o '<p id="server">.*</p>'
<p id="server">server: support=<!-- -->01800-111111<!-- --> shopOnServer=<!-- -->Bazarghar-Rahim-Laptop<!-- --> secretLength=<!-- -->31</p>

একই লাইনে দুই রকম আচরণ। SUPPORT_PHONE নতুন মান 01800-111111 দেখাল, কারণ prefix ছাড়া মান server-এ request-এর সময় পড়া হয়। কিন্তু shopOnServer এখনো Bazarghar-Rahim-Laptop, যদিও কোডটি server-এ চলছে! Build-এর পর server-এর bundle খুলে কারণ পাওয়া গেল:

"server: support=",process.env.SUPPORT_PHONE," shopOnServer=","Bazarghar-Rahim-Laptop"," secretLength=",a

অর্থাৎ NEXT_PUBLIC_ মান শুধু browser-এর কোডে নয়, server-এর কোডেও লেখা হয়ে যায়। Docs-ও বলে, build-এর সময় সব রেফারেন্স বদলে দেওয়া হয়। তাই “staging-এ শুধু env বদলে দিলেই হবে” ভাবনা এখানে ভুল প্রমাণিত হলো।

ফাঁদ ২: Client Component-এ secret পড়া

উপরের grep দেখিয়েছে, secret browser-এর JavaScript ফাইলে নেই। তাহলে কি Client Component-এ process.env.PAYMENT_SECRET লেখা নিরাপদ? একই run-এর HTML-এ দেখুন:

<p id="badge">shop=<!-- -->Bazarghar-Rahim-Laptop<!-- --> api=<!-- -->https://api.bazarghar.example<!-- --> <!-- -->secret=<!-- -->example-secret-local-0123456789</p>

Inlining-এর কৌশল খুব সাধারণ: source-এর লেখায় খুঁজে বদলে দেওয়া। নিচের ছোট মডেলটি Next.js-এর আসল compiler নয়, শুধু ধারণাটি দেখায়। দুটি জিনিস লক্ষ করুন: secret-কে হাত দেওয়া হয় না, আর process.env[name] ধরনের dynamic খোঁজাও বদলায় না। Docs-ও একই কথা বলে, dynamic lookup inline হয় না।

// build-এর সময়ের মান (নকল), যেন build machine-এর environment
const buildEnv = {
  NEXT_PUBLIC_SHOP_NAME: "Bazarghar",
  NEXT_PUBLIC_API_URL: "https://api.bazarghar.example",
  PAYMENT_SECRET: "example-secret-0123456789",
};

// একটি client component-এর source লেখা
const source = [
  'const api = process.env.NEXT_PUBLIC_API_URL;',
  'const title = process.env.NEXT_PUBLIC_SHOP_NAME + " shop";',
  'const secret = process.env.PAYMENT_SECRET;',
  'const name = "NEXT_PUBLIC_API_URL"; const dyn = process.env[name];',
].join("\n");

// শিক্ষার মডেল: শুধু process.env.NEXT_PUBLIC_X আকারের লেখা বদলায়
function inlinePublicEnv(code, env) {
  let replaced = 0;
  const out = code.replace(/process\.env\.(NEXT_PUBLIC_[A-Z0-9_]+)/g, (match, key) => {
    replaced++;
    return key in env ? JSON.stringify(env[key]) : "undefined";
  });
  return { out, replaced };
}

const { out, replaced } = inlinePublicEnv(source, buildEnv);
console.log(out);
console.log(`--- replaced ${replaced} references`);
console.log("secret value in output?", out.includes(buildEnv.PAYMENT_SECRET));

// build-এর পরে মান বদলালেও আউটপুট বদলায় না
buildEnv.NEXT_PUBLIC_API_URL = "https://staging-api.bazarghar.example";
console.log("after changing env, bundle still says:", out.split("\n")[0]);

৫ · Build-time বনাম runtime config — একটি build, অনেক পরিবেশ

এখন সমস্যাটি স্পষ্ট। Staging আর production-এর API ঠিকানা আলাদা। ঠিকানাটি NEXT_PUBLIC_ হলে প্রতিটি পরিবেশের জন্য আলাদা build লাগবে। তাহলে staging-এ যা পরীক্ষা করলেন, production-এ যাচ্ছে আরেকটি build. দুটি build একই source থেকে হলেও হুবহু এক হওয়ার নিশ্চয়তা নেই: dependency-র একটি নতুন patch, আলাদা মান, আলাদা যন্ত্র। তাই অভিজ্ঞ দলের নীতি: build once, deploy many. একবার বানানো জিনিসটিকে বলে build artifact, আর পরীক্ষা পেরিয়ে সেটিকেই পরের পরিবেশে তোলাকে বলে promotion. এর তত্ত্ব আছে Cloud & DevOps কোর্সের Artifact promotion পর্বে।

তাহলে browser-এর কোনো মান পরিবেশ ভেদে আলাদা হলে কী করবেন? কয়েকটি পথ আছে, সহজ থেকে কঠিন:

• আপেক্ষিক ঠিকানা। Browser যদি /api/... ডাকে, তাহলে যে domain-এ পাতা খোলা, সেখানেই যায়। Staging আর production-এ কোড এক থাকে, কোনো env লাগেই না। বাজারঘরের বেশির ভাগ ক্ষেত্রে এটিই যথেষ্ট।
• Server থেকে prop. একটি Server Component connection()-এর পরে process.env পড়ে মানটি Client Component-কে prop হিসেবে দেয়। Docs এই ধরনের runtime পড়াকে একটি Docker image একাধিক পরিবেশে তোলার উপায় হিসেবে দেখায়। মনে রাখুন, prop-এ যা যায় তা browser-এ যায়, তাই শুধু public মান।
• Config endpoint. একটি /api/public-config route চালুর সময় public মানগুলো JSON হিসেবে দেয়। Docs-ও বলে, runtime মান client-এ লাগলে নিজের API বানাতে হবে।

Docker image-এর ক্ষেত্রেও একই হিসাব। নিচের Dockerfile অংশটি শুধু উদাহরণ, এখানে চালানো হয়নি; পুরো আলোচনা পর্ব ৮০-তে আর Cloud & DevOps কোর্সের Dockerfile পর্বে।

# build stage: NEXT_PUBLIC_ মান এখানে লাগলে image-এই জমে যায়
ARG NEXT_PUBLIC_SHOP_NAME=Bazarghar
RUN npm run build

# run stage: secret এখানে নয়, চালানোর সময় দেওয়া হবে
ENV NODE_ENV=production
CMD ["npm", "start"]

# চালানোর সময় (উদাহরণ):
# docker run -e APP_ENV=staging -e DATABASE_URL=... bazarghar-web:57

দুটি নিয়ম এখান থেকে আসে। এক, secret কখনো ARG বা ENV দিয়ে image-এ নয়; image-এর layer আর history থেকে তা পড়া যায়। দুই, যা কিছু পরিবেশ ভেদে বদলায়, তা docker run -e বা প্ল্যাটফর্মের সেটিং দিয়ে চালানোর সময়।

1ci: npm ci && next build   # build #572deploy #57 → staging (APP_ENV=staging)3smoke test: /api/health, checkout (sandbox)4promote #57 → production (APP_ENV=production)5error rate বাড়ল? rollback → #56

Vite-এ একই গল্প: import.meta.env আর --mode

React-এর SPA, যা Vite দিয়ে বানানো (পর্ব ৫ আর ৭৯), সেখানে process.env-এর জায়গায় import.meta.env, আর prefix VITE_. Vite-এর mode ধারণাটি Next.js-এর চেয়ে নমনীয়: vite build --mode staging চালালে .env.staging পড়া হয়, অথচ build production-এর মতোই optimized থাকে। সত্যিকারের run (Vite 8.3.5; .env-এ PAYMENT_SECRET আছে, prefix ছাড়া):

$ npx vite build
dist/assets/index-DndKifQv.js  0.81 kB │ gzip: 0.47 kB
…var e={api:`https://api.bazarghar.example`,mode:`production`,prod:!0,secret:void 0};

$ npx vite build --mode staging
dist/assets/index-CtX-2e7h.js  0.82 kB │ gzip: 0.48 kB
…var e={api:`https://staging-api.bazarghar.example`,mode:`staging`,prod:!0,secret:void 0};

দুটি আলাদা ফাইল নাম, কারণ ভেতরের লেখা আলাদা। অর্থাৎ Vite-এর mode দুটি আলাদা artifact বানায়, একটি promote করা যায় না। secret:void 0 দেখাচ্ছে prefix ছাড়া মান browser-এ যায়নি। Static SPA-র সব কোডই browser-এ চলে, তাই সেখানে runtime config-এর সহজ উপায় আপেক্ষিক /api অথবা চালুর সময় একটি config.json fetch করা।

৬ · Type-safe env — ভুল মানে build-ই থেমে যাক

পর্ব ৩১-এ server চালুর মুহূর্তে Zod দিয়ে যাচাই করেছিলেন। Next.js-এ আরও আগে থামা যায়: build-এর সময়। @t3-oss/env-nextjs একটি ছোট library, যা Zod-এর মতো schema নেয়, server আর client মান আলাদা করে, আর একটি typed env object দেয়। লেখার সময়ের version 0.13.11, Zod 4.6.7.

import { createEnv } from "@t3-oss/env-nextjs";
import { z } from "zod";

export const env = createEnv({
  server: {
    DATABASE_URL: z.url(),
    PAYMENT_SECRET: z.string().min(16),
    SUPPORT_PHONE: z.string().min(1),
  },
  client: {
    NEXT_PUBLIC_SHOP_NAME: z.string().min(1),
    NEXT_PUBLIC_API_URL: z.url(),
  },
  // library-র docs: Next.js 13.4.4 বা পরের version-এ শুধু client মানগুলো লিখতে হয়
  experimental__runtimeEnv: {
    NEXT_PUBLIC_SHOP_NAME: process.env.NEXT_PUBLIC_SHOP_NAME,
    NEXT_PUBLIC_API_URL: process.env.NEXT_PUBLIC_API_URL,
  },
  emptyStringAsUndefined: true,
});

import "./env.mjs"; // build শুরুর আগেই যাচাই

/** @type {import('next').NextConfig} */
const nextConfig = {};
export default nextConfig;

Client মানগুলো কেন আলাদা করে process.env.NEXT_PUBLIC_... লিখে দিতে হলো? কারণ আগের অংশেই দেখেছেন, Next.js শুধু হুবহু লেখা রেফারেন্স বদলায়। emptyStringAsUndefined খালি মান KEY=-কে “নেই” ধরে, তাই খালি secret ফাঁক গলে যায় না। এবার .env.local সরিয়ে আর API ঠিকানা ভুল দিয়ে build চালানো হলো, সত্যিকারের run:

$ NEXT_PUBLIC_API_URL=not-a-url npx next build
▲ Next.js 16.4.4 (Turbopack)
- Environments: .env.production, .env
❌ Invalid environment variables: [
  {
    expected: 'string',
    code: 'invalid_type',
    path: [ 'PAYMENT_SECRET' ],
    message: 'Invalid input: expected string, received undefined'
  },
  {
    code: 'invalid_format',
    format: 'url',
    path: [ 'NEXT_PUBLIC_API_URL' ],
    message: 'Invalid URL'
  }
]
⨯ Failed to load next.config.mjs, see more info here https://nextjs.org/docs/messages/next-config-error

> Build error occurred
Error: Invalid environment variables
    at <unknown> (env.mjs:4:20)
exit=1

দুটি ভুল একসাথে, আর কোনো মানের লেখা নেই, শুধু নাম আর কারণ। CI-তে এই build ব্যর্থ হলে কোনো artifact তৈরিই হয় না, তাই ভুল config নিয়ে কিছু deploy হওয়ার সুযোগ থাকে না। কয়েকটি সতর্কতা:

• Library-র docs অনুযায়ী server আর client schema একই ফাইলে রাখলে server variable-এর নামগুলো client bundle-এ যেতে পারে। নাম প্রকাশ পাওয়া মানের মতো বিপদ নয়, তবে চাইলে দুটি ফাইলে ভাগ করুন।
• এই যাচাই ফাঁদ ২ ঠেকায় না: Client Component-এ সরাসরি process.env.PAYMENT_SECRET লিখলে SSR-এ তা এখনো পড়া যায়। server-only আর code review দরকার।
• CI-তে lint বা Docker build-এর মতো কাজে, যেখানে আসল secret নেই, অনেকে SKIP_ENV_VALIDATION-এর মতো একটি সুইচ রাখেন। সেটি production deploy-এর পথে কখনো চালু রাখবেন না।

৭ · Secret git-এ নয় — আর গেলে খুঁজে বের করা

Secret মানে এমন মান, যা পেলে অন্য কেউ আপনার হয়ে কাজ করতে পারে: database password, payment gateway-এর key, JWT সই করার চাবি, SMS gateway-এর token. প্রথম বেড়া .gitignore, আর নামের তালিকার জন্য একটি .env.example:

.env
.env.*
!.env.example
# Next.js-এর ডিফল্ট টেমপ্লেটও .env ফাইলগুলো ignore করে

কিন্তু .gitignore শুধু ভবিষ্যৎ আটকায়। একটি ভুল git add . আগেই হয়ে থাকলে? ল্যাবে একটি আলাদা scratch repository-তে ঠিক এই ভুলটি ইচ্ছা করে করা হলো (নকল key, লেখকের নাম Rahim). প্রথম commit-এ .env চলে গেল, দ্বিতীয় commit-এ সেটি সরিয়ে .gitignore যোগ হলো:

$ git log --oneline
8246005 chore: remove .env, add .gitignore
189a5e1 feat: add server and config
$ git ls-files
.env.example
.gitignore
server.js

এখন repository দেখতে পরিষ্কার। পরীক্ষার জন্য gitleaks নেওয়া হলো, একটি open-source secret scanner. Portable binary নামিয়ে প্রকাশিত checksum মিলিয়ে নেওয়া হলো, যাতে পথে কেউ বদলে না দেয়:

$ grep windows_x64 gitleaks_8.30.1_checksums.txt
d29144deff3a68aa93ced33dddf84b7fdc26070add4aa0f4513094c8332afc4e  gitleaks_8.30.1_windows_x64.zip
$ sha256sum gitleaks_8.30.1_windows_x64.zip
d29144deff3a68aa93ced33dddf84b7fdc26070add4aa0f4513094c8332afc4e *gitleaks_8.30.1_windows_x64.zip
$ gitleaks version
8.30.1

দুটি scan, সত্যিকারের run. প্রথমটি শুধু এখনকার ফাইল দেখে, দ্বিতীয়টি পুরো git history:

$ gitleaks dir . --no-banner
5:17PM INF scanned ~82 bytes (82 bytes) in 999µs
5:17PM INF no leaks found
exit=0

$ gitleaks git . --no-banner --redact -v
Finding:     PAYMENT_SECRET=REDACTED
Secret:      REDACTED
RuleID:      generic-api-key
Entropy:     4.923182
File:        .env
Line:        2
Commit:      189a5e1ed8c3c0dfcac7422b7afabd6553ad5512
Author:      Rahim
Email:       rahim@example.com
Date:        2026-11-02T04:00:00Z

5:17PM INF 2 commits scanned.
5:17PM WRN leaks found: 1
exit=1

এখনকার ফাইলে কিছু নেই, কিন্তু history-র commit 189a5e1-এ key পড়ে আছে। Repository কেউ clone করলে এই commit-ও পায়। --redact রিপোর্টে মানটি ঢেকে দেয়, যাতে scan-এর log নিজেই ফাঁসের উৎস না হয়। Exit code 1 হওয়ায় CI এই ধাপে থেমে যেতে পারে। আর একই টুল commit-এর আগেও চলে, একটি pre-commit hook হিসেবে। Stage করা একটি নতুন ফাইলে নকল key রেখে চালানো হলো:

$ gitleaks git --pre-commit --staged --redact -v .
Finding:     key = "REDACTED"
RuleID:      generic-api-key
File:        pay.js
Line:        1
…
5:18PM WRN leaks found: 1

Scanner ভেতরে কী করে? মূলত দুটি কাজ। এক, পরিচিত আকারের নিয়ম (regex), যেমন একটি নির্দিষ্ট প্রতিষ্ঠানের key-এর prefix. দুই, “key”, “secret”, “token”-এর মতো শব্দের পাশে বসা মানের এলোমেলোভাব মাপা, যাকে বলে Shannon entropy. “aaaa…”-এর মতো মানের entropy শূন্য, এলোমেলো key-এর অনেক বেশি। নিচের মডেলটি gitleaks নয়, তার ধারণার একটি ছোট রূপ:

// নকল লাইন: কোনোটিই আসল key নয়
const lines = [
  'const port = 4000;',
  'PAYMENT_SECRET=bzg_live_k7Qp2Xv9LmR4tW8nZc3YhJ6d',
  'const apiKey = "aaaaaaaaaaaaaaaaaaaaaaaa";',
  'DATABASE_URL=postgresql://shop:Xk29pLq7Vd@db.bazarghar.example/shop',
  'const token = process.env.API_TOKEN;',
];
// Shannon entropy: প্রতি অক্ষরে কত bit "অনিশ্চয়তা"
function entropy(s) {
  const count = {};
  for (const ch of s) count[ch] = (count[ch] || 0) + 1;
  return Object.values(count)
    .reduce((h, n) => h - (n / s.length) * Math.log2(n / s.length), 0);
}
const rules = [
  { id: "bazarghar-live-key", re: /bzg_live_[A-Za-z0-9]{24}/ },
  { id: "url-password", re: /:\/\/[^:\s]+:([^@\s]+)@/, group: 1 },
  { id: "generic-assignment", re: /(?:key|secret|token)\w*\s*[=:]\s*"?([A-Za-z0-9_\-]{16,})"?/i, group: 1, minEntropy: 3.5 },
];
lines.forEach((line, i) => {
  for (const rule of rules) {
    const m = line.match(rule.re);
    if (!m) continue;
    const secret = m[rule.group || 0];
    const h = entropy(secret);
    if (rule.minEntropy && h < rule.minEntropy) {
      console.log(`line ${i + 1}: ${rule.id} skipped (entropy ${h.toFixed(2)})`);
      continue;
    }
    console.log(`line ${i + 1}: ${rule.id} entropy=${h.toFixed(2)} secret=${secret.slice(0, 4)}…`);
    break;
  }
});

৮ · ফাঁস হলে rotation, আর secret manager

History-তে secret পাওয়া গেল। প্রথম প্রতিক্রিয়া প্রায়ই “history মুছে দিই”। কিন্তু ততক্ষণে repository কেউ clone করে থাকতে পারেন, CI-এর cache-এ থাকতে পারে, কোনো fork-এ থাকতে পারে। তাই নিয়ম: ফাঁস হওয়া secret-কে মৃত ধরে নিন। আসল প্রতিকার rotation: নতুন key বানানো, সব জায়গায় বসানো, তারপর পুরোনোটি বাতিল। History পরিষ্কার করা (যেমন git filter-repo দিয়ে) ঐচ্ছিক, পরের ধাপ। Git-এর দিক বিস্তারিত আছে Software Engineering কোর্সের Git security পর্বে।

RuleID:  generic-api-key
File:    .env   Line: 2
Commit:  189a5e1
WRN leaks found: 1

bzg_live_k7Qp…  active (leaked)
bzg_live_Nw3r…  active (new)

PAYMENT_SECRET = bzg_live_Nw3r…
deploy #58 (config only) → healthy

bzg_live_k7Qp…  revoked
bzg_live_Nw3r…  active
gateway log: পুরোনো key-এর ব্যবহার খোঁজা

$ gitleaks git --pre-commit --staged -v .
File:    pay.js
WRN leaks found: 1  → commit বাতিল

Secret manager আর KMS — এক লাইনে

ছোট প্রকল্পে হোস্টিং প্ল্যাটফর্মের env সেটিংই প্রায়ই যথেষ্ট। দল বড় হলে আর secret বাড়লে আসে secret manager: কেন্দ্রীয় সুরক্ষিত ভাণ্ডার, কে কখন পড়ল তার হিসাব, স্বয়ংক্রিয় rotation. উদাহরণ হিসেবে HashiCorp Vault, আর বড় cloud প্রতিষ্ঠানগুলোর নিজস্ব secret manager সেবা আছে। তার পেছনে থাকে KMS, যে চাবি কখনো নিজের ঘর ছাড়ে না। এই তত্ত্ব, envelope encryption আর downtime ছাড়া rotation পুরোটাই আছে Cloud & DevOps কোর্সের Secrets ও KMS পর্বে; এখানে আবার শেখানো হলো না।

Encrypted ফাইল git-এ রাখার দুটি পরিচিত পথও আছে, যা নিয়ে সাবধানে কথা বলা ভালো:

• SOPS: শুরু Mozilla-তে, এখন getsops নামে community প্রকল্প। YAML বা JSON ফাইলের key-গুলো খোলা রেখে শুধু মানগুলো encrypt করে, চাবি আসে KMS, age বা PGP থেকে। ফলে diff পড়া যায়, মান পড়া যায় না। শিখতে একটু সময় লাগে।
• dotenv-vault: dotenv-এর নির্মাতাদের টুল, encrypted .env ভাগ করার জন্য। লেখার সময় npm-এ এর শেষ আপডেট ২০২৫ সালের মাঝামাঝি, আর একই নির্মাতারা এখন dotenvx নামে আরেকটি টুল সামনে আনছেন। ব্যবহারের আগে বর্তমান অবস্থা আর docs দেখে নিন।

যে পথই নিন, চাবি (decryption key) আর encrypted ফাইল একই জায়গায় রাখলে কোনো লাভ নেই।

৯ · আলাদা database, test data, feature flag আর একটি চেকলিস্ট

Staging কখনো production database-এ নয়

প্রতিটি পরিবেশের নিজের database, নিজের user আর নিজের password. কারণ সরল: staging-এ ভাঙা কোড চলে, পরীক্ষার script চলে, কেউ ভুল করে prisma migrate reset চালাতে পারেন। সেই কাজ যদি production-এর connection string দিয়ে হয়, ক্রেতার অর্ডার মুছে যায়। ২০১৭ সালের জানুয়ারিতে GitLab-এর প্রকাশিত postmortem অনুযায়ী, একজন প্রকৌশলী গভীর রাতে কাজ করার সময় ভুল database server-এ ডেটা মোছার কমান্ড চালান, আর কয়েক ঘণ্টার ডেটা হারায়; ঘটনাটি দেখায় যে “কোন যন্ত্রে আছি” প্রশ্নের ভুল কত দামি। প্রতিরোধের স্তর:

• Staging-এর credential দিয়ে production-এ ঢোকাই সম্ভব নয়, network আর user দুই দিক থেকে। এই নীতির নাম least privilege.
• অ্যাপ চালুর যাচাইয়ে host-এর নিয়ম, যেমন আগের runnable উদাহরণের db-prod পরীক্ষা।
• Destructive script-এর শুরুতে APP_ENV === "production" হলে থেমে যাওয়া।
• Terminal-এর prompt-এ বা database টুলের রঙে পরিবেশের নাম, যাতে চোখেও পড়ে।

Staging-এ বাস্তবের মতো ডেটা দরকার, কিন্তু আসল ক্রেতার ফোন নম্বর আর ঠিকানা নয়। Seed script দিয়ে নকল ডেটা (পর্ব ৪০), আর test-এ factory ও builder (পর্ব ৭৭)। Production-এর কপি লাগলে আগে মুখোশ পরানো: নাম, ফোন, ঠিকানা বদলে। Test database তৃতীয় একটি আলাদা জগৎ, যা প্রতিবার খালি থেকে শুরু হয় (পর্ব ৭৫)।

Feature flag — config দিয়ে feature চালু-বন্ধ

নতুন checkout পাতা তৈরি। কিন্তু একবারে সব ক্রেতাকে দেখানো ঝুঁকির। Feature flag কোড deploy আর feature চালুকে আলাদা করে: কোড production-এ আছে, কিন্তু একটি config মান ঠিক করে কে দেখবেন। এতে তিনটি সুবিধা: percentage rollout (প্রথমে ১০%), QA দলের জন্য আগেভাগে চালু, আর বিপদে এক সুইচে বন্ধ, যাকে বলে kill switch. মূল কৌশল একটি stable hash: একই ব্যবহারকারী প্রতিবার একই দলে পড়েন, তাই পাতা রিফ্রেশ করলে checkout বদলে যায় না।

// FNV-1a: একই লেখা দিলে সবসময় একই সংখ্যা
function fnv1a(text) {
  let h = 0x811c9dc5;
  for (let i = 0; i < text.length; i++) {
    h ^= text.charCodeAt(i);
    h = Math.imul(h, 0x01000193) >>> 0;
  }
  return h;
}
// flag-এর নামও hash-এ যায়, তাই প্রতিটি flag-এ আলাদা দল পড়ে
function bucket(flagName, userId) {
  return fnv1a(`${flagName}:${userId}`) % 100; // 0..99
}
function isEnabled(flag, user) {
  if (!flag.enabled) return false;                       // kill switch
  if (flag.allowUsers.includes(user.id)) return true;    // QA দল সবসময়
  return bucket(flag.name, user.id) < flag.rolloutPercent;
}
const flag = { name: "new-checkout", enabled: true, rolloutPercent: 10, allowUsers: ["qa-1"] };
let on = 0;
for (let i = 1; i <= 10000; i++) if (isEnabled(flag, { id: `user-${i}` })) on++;
console.log(`10% rollout: ${on} of 10000 users see new checkout`);
const u = { id: "user-42" };
console.log("user-42 bucket:", bucket(flag.name, u.id), "same again:", bucket(flag.name, u.id));
console.log("qa-1 enabled:", isEnabled(flag, { id: "qa-1" }));
flag.rolloutPercent = 50;
let stillOn = 0, before = 0;
for (let i = 1; i <= 10000; i++) {
  const b = bucket(flag.name, `user-${i}`);
  if (b < 10) { before++; if (b < 50) stillOn++; }
}
console.log(`raise to 50%: ${stillOn} of the first ${before} keep it on`);
flag.enabled = false;
console.log("kill switch, qa-1 enabled:", isEnabled(flag, { id: "qa-1" }));

এই ছোট কোডের মান কোথা থেকে আসবে? সবচেয়ে সরল পথ env variable, যেমন FLAG_NEW_CHECKOUT_PERCENT=10; তবে বদলাতে restart লাগে। তার পরের ধাপ database-এর একটি table, যা admin পাতা থেকে বদলানো যায়। আরও বড় হলে hosted সেবা, যেমন LaunchDarkly, বা নিজে চালানো যায় এমন open-source Unleash, GrowthBook, Flagsmith; এগুলো শুধু উদাহরণ, কোনোটির সুপারিশ নয়। ভেন্ডর বদলানো সহজ রাখতে CNCF-এর OpenFeature নামে একটি সাধারণ API মানদণ্ডও আছে। দুটি সাবধানতা: পুরোনো flag নিয়মিত মুছে ফেলুন, আর পুরোনো flag-এর নাম নতুন অর্থে কখনো ব্যবহার করবেন না। পর্ব ৩১-এ বলা Knight Capital ঘটনায় পুরোনো একটি flag নতুন অর্থে ব্যবহারও একটি ভূমিকা রেখেছিল বলে প্রকাশিত প্রতিবেদনে উল্লেখ আছে।

প্রতিটি pull request-এর জন্য preview environment: আলাদা URL, sandbox key, ছোট নিজস্ব বা ভাগ করা database. এখানে একটি বড় সতর্কতা: বাইরের কারও fork থেকে আসা pull request-এ production বা staging-এর secret কখনো দেবেন না, কারণ সেই কোড তিনি নিজেই লিখেছেন। কীভাবে এটি CI-তে সাজাবেন, পর্ব ৮১-তে; কোন প্ল্যাটফর্ম কী দেয়, পর্ব ৮২-তে।

চেকলিস্ট — নতুন পরিবেশ বা deploy-এর আগে

• .env* ফাইল .gitignore-এ, .env.example-এ শুধু নাম
• gitleaks বা অনুরূপ scanner pre-commit-এ আর CI-তে, পুরো history একবার scan করা
• Build-এর সময় env schema যাচাই; ভুল হলে build থামে, মান log-এ ছাপে না
• কোনো NEXT_PUBLIC_ বা VITE_ নামে secret নেই; Client Component-এ secret-এর নাম নেই
• পরিবেশ ভেদে বদলানো মান runtime-এ; একই artifact staging থেকে production-এ ওঠে
• প্রতিটি পরিবেশে আলাদা database, আলাদা credential, আলাদা payment key
• Staging-এ নকল বা মুখোশ পরানো ডেটা; test database আলাদা
• প্রতিটি secret কোথায় আছে আর কে বদলাবেন তার তালিকা; ফাঁস হলে rotation-এর অনুশীলন করা
• Feature flag-এর kill switch কাজ করে কি না staging-এ পরীক্ষা করা

১০ · AI-এর যুগে environment আর secret

Config আর secret-এর ভুল চলার সময় চোখে পড়ে না। অ্যাপ চলে, পাতা খোলে, আর secret চুপচাপ browser-এ বা git-এ পৌঁছে যায়। AI এই জায়গায় কয়েকটি পরিচিত ভুল করে:

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

• প্রতিটি option আর package আমার version-এর official docs-এ পেয়েছি
• next build-এর পর .next/static আর পাতার HTML-এ নকল secret খুঁজে পাইনি
• একটি জরুরি variable মুছে build চালিয়েছি; build থেমেছে, বার্তায় মান নেই
• Diff পড়েছি, gitleaks চালিয়েছি; কোনো .env বা key commit হয়নি
• নতুন dependency থাকলে কেন লাগল বুঝেছি