DEV Community: Amit Shukla

RAG evaluation: how to know if your retrieval is actually good

Amit Shukla — Tue, 29 Sep 2026 13:15:44 +0000

You built a RAG app, asked it five questions in the demo, and every answer sounded right. That is not evaluation, that is vibes. The moment a real user asks something slightly off the beaten path, retrieval quietly returns the wrong chunks, the model answers confidently anyway, and nobody notices until a customer does.

RAG systems fail silently. A bad retrieval does not throw an error, it just hands the model the wrong context, and the model, doing exactly what it is built to do, writes a fluent, convincing, wrong answer on top of it. Without a real evaluation process, you find out about these failures from users, not from tests.

Why "it sounded right" is not evaluation

Reading five outputs and nodding is not measurement, it is spot-checking, and spot-checking only catches the failures that happen to land in your five questions. Retrieval quality is not a single number you eyeball, it is a set of properties that need to be checked against a real, repeatable set of queries with known correct answers.

The two systems working together, retriever and generator, fail differently and need to be evaluated separately before you evaluate them together. A generator can write a great answer from bad context. A retriever can find the perfect chunk and still get a bad answer if the generator ignores it. Blending both into one end-to-end "did it sound good" check hides which half is actually broken.

Build an eval set before you build more features

The single highest leverage thing you can do is create a small, real set of query, expected-answer, expected-source triples. Something like:

{
  "query": "What is the default max_connections value in Postgres?",
  "expected_chunk_ids": ["postgres-pooling-03"],
  "expected_answer_contains": ["100"]
}

Twenty to fifty of these, pulled from real questions your users actually ask or would ask, beats a thousand synthetic ones nobody will trust. Write them once, run them on every change to chunking, embedding model, or prompt, and you have a real signal instead of a feeling.

Retrieval metrics: is the right chunk even in the list

Before touching generation quality, check whether the retriever is finding the right source material at all.

Recall@k asks: of the chunks you actually needed, how many showed up in the top k results. If the right chunk is buried at position 15 and you only pass the top 5 to the model, recall@5 is 0, and no amount of prompt engineering fixes that. This is usually the first thing to check when answers go wrong, because a generation problem downstream of a retrieval miss looks identical to a bad prompt.

Precision@k asks the opposite: of what you retrieved, how much was actually relevant. High recall with low precision means you are burying the right chunk in a pile of noise, which still hurts the generator, since irrelevant context competes for the model's attention and can get woven into a wrong answer.

MRR (Mean Reciprocal Rank) captures how high up the correct result lands, not just whether it appears. A system that ranks the right chunk first every time scores very differently from one that eventually finds it at position 8, even if raw recall looks similar.

A simple way to compute recall@k against your eval set:

def recall_at_k(retrieved_ids, expected_ids, k):
    top_k = set(retrieved_ids[:k])
    hits = top_k & set(expected_ids)
    return len(hits) / len(expected_ids)

Run this across your eval set every time you change chunking strategy, embedding model, or index settings, and you get a real before/after number instead of a guess.

Generation metrics: did the model actually use what it was given

Once retrieval is solid, check whether the generator is grounded in what it received, not hallucinating on top of it.

Faithfulness checks whether every claim in the answer is actually supported by the retrieved context. An answer can be well written and completely unsupported by the sources it was supposedly built from, this is the specific failure mode that makes RAG dangerous in production, since it looks exactly like a correct answer.

Answer relevance checks whether the response actually addresses the question asked, independent of whether it's grounded, since a model can retrieve the right chunk and still wander off and answer a related but different question.

A common, practical pattern is using a second LLM call as a judge, asking it to check faithfulness against the retrieved context directly:

judge_prompt = f"""
Context: {retrieved_context}
Answer: {generated_answer}

Does the answer contain any claim not supported by the context?
Respond with only: SUPPORTED or UNSUPPORTED
"""

This is not perfect, an LLM judge has its own blind spots, but it is far better than nothing and it is cheap enough to run against your whole eval set on every change.

Where teams actually get this wrong

Testing only the happy path. Your eval set should include queries with no good answer in the corpus, ambiguous questions, and queries phrased nothing like your documents. A retriever that only works when the question echoes the document's wording will fail constantly in production.

Never re-running the eval set. Building it once and never running it again defeats the purpose. Every change to chunking, embedding model, or prompt needs to run against the same eval set, otherwise you have no idea if you just made things better or worse.

Optimizing retrieval and generation together, blindly. If an answer is wrong, check retrieval first. Fixing a prompt to compensate for consistently bad retrieval just hides the real problem and makes it harder to fix later.

Takeaway

A RAG app that sounds convincing in a five-question demo is not a RAG app you've evaluated, it's one you've gotten lucky with. Build a real eval set from actual questions, measure retrieval with recall@k and precision@k before you touch the prompt, and check faithfulness on generation once retrieval is solid. The failures are silent by default, the only way to catch them before a user does is to actually measure for them.

Structured logging: why print statements do not scale past one service

Amit Shukla — Thu, 24 Sep 2026 13:15:25 +0000

console.log('user logged in', userId) is fine when there is one process and one terminal. The moment there are two services, three instances of each, and a log aggregator collecting all of it into one place, that same line becomes a string sitting in a pile of other strings, and the only way to find it again is grep and hope.

Structured logging is not a bigger word for logging more. It is logging in a shape a machine can filter, group, and query, instead of a shape only a human eyeballing a terminal can read.

What "unstructured" actually costs you

A typical unstructured log line looks like this:

2026-03-14 09:12:01 INFO user logged in userId=8842 from 203.0.113.4

Readable, sure. But ask it a real question: how many logins came from this IP in the last hour, across all three instances of the auth service. There is no field called ip to filter on, there is a string that happens to contain an IP address somewhere after the word from. Every query against logs like this becomes a regex, and every regex is one log format change away from silently missing everything.

Multiply that by every service you run, each with its own slightly different log phrasing, and log aggregation stops being useful right around the time you actually need it, during an incident, at 2 a.m., under pressure.

What structured logging looks like instead

Same event, structured:

{
  "timestamp": "2026-03-14T09:12:01.402Z",
  "level": "info",
  "service": "auth",
  "instance": "auth-7f9c2",
  "message": "user logged in",
  "userId": 8842,
  "ip": "203.0.113.4",
  "requestId": "9c1d2e3f"
}

Now "how many logins from this IP in the last hour" is a real query: filter service:auth AND ip:203.0.113.4 AND message:"user logged in", no regex, no guessing at format. Every field is addressable because every field is actually a field, not a substring.

The fields that matter most

Not every field needs to be there every time, but a few show up in almost every useful log line:

timestamp, in a consistent format, ideally ISO 8601 with milliseconds. Without it, ordering events across services during an incident is guesswork.

level, so error and warn can be filtered separately from routine info noise, and alerting can watch one field instead of parsing text for the word "error".

service and instance, so a log aggregator pulling from twenty running processes can tell you which one actually produced a given line.

requestId (or traceId), generated once at the edge of a request and passed through every service that touches it. This is the single field that turns a pile of unrelated log lines into a story you can follow end to end.

message, a short human-readable description, kept separate from the structured fields around it rather than having the fields baked into the sentence.

Doing it in code

A raw console.log gives you none of this by default. A small logging library fixes that with almost no extra code:

// logger.js
const pino = require('pino');

const logger = pino({
  level: process.env.LOG_LEVEL || 'info',
  base: { service: 'auth', instance: process.env.HOSTNAME },
  timestamp: pino.stdTimeFunctions.isoTime,
});

module.exports = logger;

// wherever a request is handled
const logger = require('./logger');

app.use((req, res, next) => {
  req.log = logger.child({ requestId: req.headers['x-request-id'] || crypto.randomUUID() });
  next();
});

app.post('/login', (req, res) => {
  // ...
  req.log.info({ userId: user.id, ip: req.ip }, 'user logged in');
  res.sendStatus(200);
});

logger.child() is the important part. It creates a logger that automatically stamps every line with the request's requestId, so nothing downstream in that request has to remember to pass it along by hand. Every log call inside that request already carries the field that ties it back to everything else that happened during it.

The `requestId` is what makes multi-service logs useful

A single request in a real system usually touches more than one service: an API gateway, an auth service, maybe a database proxy, maybe a queue. Without a shared requestId generated once and forwarded through every hop (usually as a header like x-request-id), each service's logs are an isolated island. With it, a single filter across your aggregator, requestId:9c1d2e3f, reconstructs the entire path a request took, across every service, in order, in one view.

This is the difference structured logging actually buys you. It is not about making individual log lines prettier, it is about making an incident across five services searchable as one story instead of five separate greps that you have to correlate by hand, by timestamp, while something is on fire.

What to avoid

Do not log secrets. Passwords, tokens, full credit card numbers, anything with compliance implications, should never land in a structured field either, it is just as searchable and just as leaked if the log store is ever exposed.

Do not over-nest. A field three levels deep in JSON is harder to query in most log tools than a flat field with a longer name. user.address.city works, but a flatter userCity is often easier to filter on depending on your aggregator.

Do not log everything at info. If every line is info, level stops being a useful filter. Reserve warn for things that need attention but did not break anything, and error for things that did.

Takeaway

console.log is fine for one process on your own machine. The moment logs need to be searched, filtered, or correlated across more than one running instance, they need to be data, not sentences. A structured logger with a consistent service, level, timestamp, and a requestId that travels with the request costs a few lines of setup and turns "grep and hope" into an actual query, right when you need that query the most.

Postgres connection pooling: why your app runs out of connections under load

Amit Shukla — Tue, 22 Sep 2026 13:17:00 +0000

It works fine in staging. A handful of people click around, everything responds, nobody notices anything. Then it goes to production, real traffic shows up, and somewhere in your logs: FATAL: sorry, too many clients already. Nothing about your query logic changed. What changed is how many connections are open at once, and Postgres has a hard ceiling on that number.

What a connection actually costs

In most databases, a connection is cheap, a lightweight thread or an entry in a pool. In Postgres, a connection is a dedicated operating system process. Every client that connects gets its own backend process, with its own memory overhead, typically several megabytes just to exist before it runs a single query.

That process model is part of why Postgres is so stable, an unstable connection can't take down another one's memory space, but it also means connections are not free, and there's a hard limit on how many can exist at once: max_connections, which defaults to 100.

A hundred sounds like a lot until you count how many things are trying to hold one open at the same time.

Why apps blow through it so fast

Connection-per-request, no pooling. Open a new connection at the start of a request, close it at the end. Under low traffic this is invisible. Under real concurrency, you can have hundreds of requests in flight, each holding its own connection, and you hit the ceiling before any single query was slow.

Serverless functions. Each cold start can open its own connection, and serverless platforms scale by spinning up more instances under load, exactly when you can least afford more connections. A traffic spike creates a connection spike in the worst possible direction.

ORMs that don't clean up. A pool that never releases idle connections, or a code path that throws before the finally that returns the connection, leaks connections one request at a time until the ceiling is gone.

Multiple app instances, each with their own pool. If you run ten instances of your app and each opens a pool of twenty connections, that's two hundred connections against a Postgres server that allows one hundred, before a single one of them is even under load.

The pattern that causes it

// a new connection every request, never reused
app.get('/orders', async (req, res) => {
  const client = new Client(connectionString);
  await client.connect();
  const result = await client.query('SELECT * FROM orders');
  await client.end();
  res.json(result.rows);
});

Fine at ten requests a second. At a few hundred concurrent requests, you're opening and holding that many real Postgres processes at once.

The fix inside your app: an actual pool

// one shared pool, connections are reused, not recreated
const pool = new Pool({ connectionString, max: 10 });

app.get('/orders', async (req, res) => {
  const result = await pool.query('SELECT * FROM orders');
  res.json(result.rows);
});

A pool holds a fixed number of real connections open and hands them out to whichever request needs one, then takes them back when the query finishes. Requests queue briefly for a free connection instead of each opening a new one. This alone fixes the connection-per-request problem for a single, always-on server.

The fix across many instances: an external pooler

An in-process pool doesn't help once you have many instances, each one still opens its own set of real connections, and they all add up against the same max_connections. The fix here is a pooler that sits between your app and Postgres: PgBouncer is the standard one.

PgBouncer accepts thousands of client connections and multiplexes them onto a small, fixed number of real Postgres connections, handing out an actual connection only for the duration of a transaction, then returning it to the pool the moment the transaction ends. A hundred app instances can each think they have their own pool of client connections to PgBouncer, while Postgres itself only ever sees a few dozen real ones.

Sizing it, and the tradeoff nobody mentions

More pool slots is not automatically better. If Postgres allows 100 connections and you reserve some for admin and migrations, your actual budget might be 80. Ten app instances each opening a pool of 20 is 200, already over budget, regardless of how idle most of those connections are most of the time. Pool size has to be planned against max_connections divided across every instance that connects, not set per instance in isolation.

The tradeoff with PgBouncer specifically: its fastest mode, transaction pooling, breaks anything that depends on session state persisting across queries; prepared statements, session-level settings, advisory locks, LISTEN/NOTIFY. If your app relies on those, you either avoid transaction mode and accept fewer effective connections, or restructure the code that depends on session state.

Takeaway

Postgres connections are real processes with a hard, low ceiling, not a cheap resource you can hand out per request. Pool inside your app so you reuse connections instead of recreating them, and once you're running more than one instance, put an external pooler like PgBouncer in front of Postgres so the number of real connections stays fixed no matter how many app instances or serverless functions are asking for one.

React Server Components vs traditional SSR: what changed and why it matters

Amit Shukla — Thu, 17 Sep 2026 20:01:03 +0000

People use "SSR" and "Server Components" like they're the same idea wearing a different name. They're not. Traditional server side rendering and React Server Components solve different problems, and mixing them up leads to either overbuilding a simple page or missing out on a real reduction in what you ship to the browser.

What traditional SSR actually does

Server side rendering, the kind React has done since renderToString existed, runs your entire component tree on the server for the first request and sends back real HTML. That's the win: the user sees content immediately instead of a blank page waiting for JavaScript to load and run.

But the server's job isn't done once that HTML ships. The client still downloads the JavaScript for every component in that tree, then re-runs it in the browser to attach event handlers and make the page interactive. That step is hydration, and it means the same render work happens twice, once on the server to produce HTML, once on the client to make it interactive, and the client has to download and execute the code for all of it, including the parts of the page that never do anything interactive at all.

A list of blog post previews with no buttons, no state, nothing to click, still ships its full component code to the browser and still gets hydrated, purely because it was part of the same tree as something that actually needed interactivity.

What Server Components actually change

A Server Component runs only on the server. Not "server first, then also client." Only the server. Its code, and its dependencies, never reach the browser at all. What gets sent to the client is a special serialized description of the rendered output, not the component's source, not its imports, none of it.

Interactivity still exists, you opt into it explicitly with 'use client' at the top of a file. That marks a component as one that does need to run and hydrate in the browser, because it holds state, uses a hook, or responds to events. Everything else, by default, stays server-only.

This is an actual architectural split, not a performance tweak. You're choosing, per component, whether its code ships to the browser at all.

Before and after

A traditional approach: the whole page, including the static list, is one client-rendered (or hydrated) tree.

// everything here ships to the browser and gets hydrated
export default function PostList({ posts }) {
  return (
    <ul>
      {posts.map((p) => (
        <li key={p.id}>
          {p.title}
          <LikeButton postId={p.id} />
        </li>
      ))}
    </ul>
  );
}

With Server Components, the list itself, and the data fetching behind it, stays on the server. Only the interactive part opts in.

// PostList.jsx — Server Component, never ships to the client
export default async function PostList() {
  const posts = await db.posts.findMany(); // direct backend access, no API route
  return (
    <ul>
      {posts.map((p) => (
        <li key={p.id}>
          {p.title}
          <LikeButton postId={p.id} />
        </li>
      ))}
    </ul>
  );
}

// LikeButton.jsx — Client Component, this is the only part hydrated
'use client';
export default function LikeButton({ postId }) {
  const [liked, setLiked] = useState(false);
  return <button onClick={() => setLiked(!liked)}>{liked ? 'Liked' : 'Like'}</button>;
}

Same visual result. The list's rendering code, its data fetching logic, and its dependencies never leave the server. The only JavaScript the browser downloads and hydrates is the tiny like button.

What this actually buys you

Smaller client bundles. Not marginally, meaningfully, because entire categories of code, data access layers, markdown parsers, formatting libraries, anything only used to produce the server-rendered output, simply never ship.

Direct backend access. A Server Component can query a database or call an internal service directly, no separate API route needed just to get data into the page.

Streaming by default. Server Components can stream their output as it becomes ready, so slow data doesn't block fast data from rendering.

Where this gets misused

It needs framework support. This isn't a flag you flip in any React app, it's a rendering convention that Next.js's App Router (and a small number of other frameworks) actually implements. Reaching for it outside that support gets you nothing.

No hooks, no state, no browser APIs inside a Server Component. useState, useEffect, window, none of it works there, because the component never runs in a browser. That logic has to live in a Client Component.

Sequential fetches still create waterfalls. Moving data fetching to the server doesn't automatically parallelize it. Awaiting one fetch before starting the next is still slow, on the server or the client, fix it the same way you always would, start the requests together and await them together.

Takeaway

Traditional SSR answers "how do we get HTML to the browser fast." Server Components answer a different question: "does this component's code need to reach the browser at all." Most pages have far more content that never needed to be there than interactive pieces that do, and that's exactly the part Server Components let you stop shipping.

Kubernetes readiness and liveness probes: what they actually protect you from

Amit Shukla — Tue, 15 Sep 2026 13:15:41 +0000

A pod can be Running and still be useless. The container process is alive, the port is open, and every request that hits it times out anyway, because the database connection pool hasn't finished warming up, or a downstream dependency is unreachable, or the app is stuck in a loop it will never recover from on its own.

Kubernetes has two checks for exactly this, livenessProbe and readinessProbe. They sit next to each other in the same YAML block, take the same shape, and do almost nothing alike.

What liveness actually does

A liveness probe answers one question: is this process still working, or should it be killed and restarted.

If the probe fails enough times in a row, Kubernetes kills the container and starts a fresh one. That's the entire mechanism. It exists for the case where your process is technically running but permanently stuck, a deadlock, a hung thread, a memory leak that's wedged the event loop. Restarting is the only fix, and liveness is what triggers it automatically instead of you finding out from an alert three hours later.

What it does not do: protect you from slow startup, temporary unavailability, or a dependency being down. If your liveness check fails because the database is briefly unreachable, Kubernetes restarts a perfectly healthy process, which does nothing to fix the database and just adds a few seconds of extra downtime while the container comes back up.

What readiness actually does

A readiness probe answers a different question: should this pod currently receive traffic.

If it fails, the pod is pulled out of the Service's list of endpoints. Nothing gets restarted. The container keeps running, Kubernetes just stops routing requests to it until the probe passes again. This is what you want during startup, while dependencies are still initializing, and during temporary trouble, when a downstream service is degraded and you'd rather drain traffic away than serve errors.

Readiness is safe to make strict. Liveness is not.

The mistake that causes the most damage

Pointing both probes at the same endpoint, or writing a liveness check that depends on downstream services.

// dangerous as a liveness check
app.get('/healthz', async (req, res) => {
  await db.query('SELECT 1');
  await redis.ping();
  res.sendStatus(200);
});

The moment the database is slow or Redis hiccups, every pod running this as its liveness check starts failing and getting restarted, all at once, across the whole deployment. You just turned a downstream blip into a full outage of your own service, and a restart storm on top of it, since the new containers boot up, immediately fail the same check because the dependency is still down, and get killed again.

What each check should actually look like

Liveness should only answer "is the process itself alive," nothing more.

// liveness: just prove the event loop is responsive
app.get('/healthz', (req, res) => {
  res.sendStatus(200);
});

Readiness should check the things that actually determine whether this pod can serve a request correctly.

// readiness: are the things we depend on actually up
app.get('/ready', async (req, res) => {
  try {
    await db.query('SELECT 1');
    res.sendStatus(200);
  } catch {
    res.sendStatus(503);
  }
});

And the pod spec pointing at each:

livenessProbe:
  httpGet:
    path: /healthz
    port: 3000
  initialDelaySeconds: 10
  periodSeconds: 10
  failureThreshold: 3

readinessProbe:
  httpGet:
    path: /ready
    port: 3000
  initialDelaySeconds: 5
  periodSeconds: 5
  failureThreshold: 3

Tuning that actually matters

initialDelaySeconds on liveness should be longer than your worst-case startup time. If your app can take 20 seconds to boot under load, and liveness starts checking at 10 seconds with a low failure threshold, you'll get restart loops on your slowest starts, which makes the slow start even slower.

failureThreshold and periodSeconds together define how long a probe has to fail before something happens. Three failures at ten second intervals gives you thirty seconds of grace. Too short and normal jitter triggers unnecessary restarts or traffic pulls. Too long and a genuinely stuck pod keeps eating requests for a while before anyone notices.

Never let liveness depend on anything outside the process. If it can fail because of a network call, a database, another service, it will eventually cause a restart storm during exactly the incident where you can least afford one.

Readiness can and should depend on those things. That's the entire point of having it separate. Use it to pull a pod out of rotation the moment it can't correctly serve a request, and let it rejoin automatically the moment it can again, with no restart, no lost in-flight work on the other healthy pods.

Takeaway

Liveness restarts a stuck process. Readiness controls whether a pod gets traffic. Keep liveness dumb and self-contained so it only fires when the process itself is actually broken, and keep readiness honest about your real dependencies so Kubernetes can route around trouble instead of amplifying it.

Self-hosting open source is easy. Running it in production is not.

Amit Shukla — Thu, 10 Sep 2026 19:24:53 +0000

You picked an open source tool on purpose. Maybe it was n8n instead of a per-task automation SaaS, Keycloak instead of paying per active user for auth, Postgres and Grafana and Mattermost instead of three separate subscriptions that each want a seat license. The pitch is good: own your data, no per-seat bill, no vendor deciding your roadmap.

You run docker compose up. It works. You show the team. Everyone is happy.

Then it goes to production, and the actual job starts.

The work that is not in the README

The README gets you a running process. Keeping that process healthy, safe, and recoverable for the next two years is a different list: sizing and provisioning, OS patching, application updates that don't break your config or schema, TLS that renews itself, backups that are off-host and actually tested, monitoring that warns you before the disk fills, email that gets delivered instead of spam-filtered, a firewall and some answer for volumetric attacks, secret and log rotation, and tracking CVE disclosures for every app you run, forever.

None of this is hard in isolation. All of it together, across five or six self-hosted apps, is a part time job. And it usually lives in one engineer's head.

The two options most teams settle for

Do it yourself on a VPS. Works right up until the person who set it up is on leave during an incident, or the one undocumented upgrade step gets skipped, or a restore is needed for the first time and nobody has tested one. The software is free. The operational knowledge is expensive and fragile.

Pay for the vendor's hosted version. Faster to start, but often back to per-seat pricing, your data on their infrastructure, and you've given up the control that made you choose open source. For some tools the managed tier costs several times the raw compute.

There is a third option: a managed layer on top of the open source software you already chose, one that leaves you with full root access and your own data.

What Elestio actually does

Elestio runs that layer. Pick an app from a catalog of 400+ open source templates, pick where it runs, a major cloud provider and region of your choice, your own virtual machines, or your own hardware on premise, and it deploys onto a dedicated instance, not a shared box.

From there, everything on that operational list is already handled:

Automated encrypted backups, off host, with retention, and restore that's actually tested
Monitoring with alerting on the things that actually page you
Automatic OS patching and application updates, with a rollback path
Managed SMTP so outbound mail is set up and deliverable
TLS certificates that issue and renew on their own
A firewall and DDoS protection in front of the instance
Built-in CI/CD if you're deploying your own code alongside
Support that covers the whole stack, not just the VM

You keep full root access. It's your instance and your data, exportable any time. Billing is a flat fee on top of compute, not per user, so growing your team doesn't grow your bill.

Getting started takes minutes, not a sprint

Pick a template, choose a region, and Elestio provisions the instance with backups, monitoring, updates, TLS, and a firewall already configured before your first request even hits it. No YAML to write first, no runbook to build before you're allowed to go live.

Most teams have their first app running in under ten minutes.

Try Elestio free →

Takeaway

Open source being free to license doesn't make it free to operate. Backups, patching, updates, monitoring, mail, and security tracking are the real cost, and they show up the moment you're in production. Elestio is the fastest way to get all of that handled from day one, so your team spends its time on the product, not the platform underneath it.

Multi-stage Docker builds: ship the artifact, not the build shop

Amit Shukla — Thu, 10 Sep 2026 19:14:54 +0000

Most Node images I inherit are somewhere north of a gigabyte. The app inside is maybe 40 MB. The other gigabyte is the build shop: compilers, dev dependencies, the npm cache, a full copy of the source, and whatever the base image shipped with.

That gigabyte costs you every day. Slower pulls on every deploy and every autoscale event. More layers for your scanner to chew through. A bigger surface for a CVE to land on. And a longer gap between "push" and "running in production".

Multi-stage builds fix this without touching your application code. Here is how they work and how to get the details right.

What ends up in a single stage image

When you write a normal Dockerfile, every instruction adds a layer, and every layer stays in the final image. A typical Node build looks like this:

FROM node:20
WORKDIR /app
COPY package*.json ./
RUN npm ci
COPY . .
RUN npm run build
CMD ["node", "dist/server.js"]

The final image now contains:

node:20, which is Debian plus the full Node toolchain, around 1.1 GB before you add anything
every dependency, including the dev ones you only need to compile
the npm cache left behind by npm ci
your entire source tree, not just the compiled output
any build artifacts you generated on the way

You run node dist/server.js. Everything else is dead weight that ships anyway.

The multi-stage pattern

A multi-stage Dockerfile has more than one FROM. Each FROM starts a new stage with its own filesystem. You do the messy work in an early stage, then start a clean final stage and copy in only what you need with COPY --from.

FROM node:20 AS build
WORKDIR /app
COPY package*.json ./
RUN npm ci
COPY . .
RUN npm run build

FROM node:20-slim
WORKDIR /app
COPY package*.json ./
RUN npm ci --omit=dev
COPY --from=build /app/dist ./dist
CMD ["node", "dist/server.js"]

Two things changed:

The first stage is named build with AS build. It installs everything and compiles. None of its layers reach the final image.
The second stage starts from node:20-slim, a much smaller base. It installs production dependencies only, then copies the compiled dist folder out of the build stage.

The compilers, the dev dependencies, and the source tree never make it into the image you ship. Same build, a fraction of the size.

Get these four details right

Name your stages

Use AS <name> on stages you copy from, then reference them in COPY --from=<name>. You can also copy from an external image directly, for example COPY --from=nginx:latest /etc/nginx/nginx.conf ./, which is handy for grabbing a single binary or config file.

Do not copy node_modules across stages

It is tempting to COPY --from=build /app/node_modules ./node_modules and skip a second install. Do not. The build stage has dev dependencies mixed in, and native modules may have compiled against a different base image. Run npm ci --omit=dev in the final stage so you get a clean production tree that matches the runtime.

Order instructions so the cache survives

Docker caches each layer and reuses it until something upstream changes. Copy your lockfiles and install before you copy the rest of the source:

COPY package*.json ./
RUN npm ci
COPY . .

Now a change to your application code invalidates only the COPY . . layer and everything after it. The dependency install, which is the slow part, stays cached. Reverse those lines and every one line code change reinstalls everything.

Go smaller on the final base

node:20-slim drops most of the Debian extras. For a bigger cut, gcr.io/distroless/nodejs20 ships Node and nothing else, no shell, no package manager. It is stricter to debug but the attack surface is tiny. Whatever you pick, add a non-root user:

FROM node:20-slim
WORKDIR /app
COPY package*.json ./
RUN npm ci --omit=dev
COPY --from=build /app/dist ./dist
USER node
CMD ["node", "dist/server.js"]

The same feature, other uses

Multi-stage is not only about size.

One Dockerfile, several targets. Add a test stage and build just that stage in CI with docker build --target test .. Your test image and your production image come from the same file and the same base layers.

FROM node:20 AS build
# ... install and compile ...

FROM build AS test
RUN npm run lint && npm test

FROM node:20-slim AS production
# ... copy artifact ...

Pulling a tool without installing it. Need dockerize or a specific CLI at runtime? Copy the single binary from its published image in a stage instead of running a package manager in your final image.

What this looks like in numbers

On a plain Express and TypeScript service:

Single stage on node:20: about 1.1 GB
Multi-stage with node:20-slim and --omit=dev: about 180 MB
Multi-stage with distroless: about 130 MB

Pull time on a cold node drops from tens of seconds to a few. Your scanner has less to report. And nothing in the image can compile code or run a shell that does not need to.

Takeaway

Build with the full toolchain in an early stage. Start the final stage from the smallest base you can debug, install production dependencies only, and copy in just the artifact. Name your stages, keep your install layer above your source copy, and run as a non-root user. It is a ten line change to your Dockerfile and it pays off on every deploy.

DEV Community: Amit Shukla

RAG evaluation: how to know if your retrieval is actually good

Why "it sounded right" is not evaluation

Build an eval set before you build more features

Retrieval metrics: is the right chunk even in the list

Generation metrics: did the model actually use what it was given

Where teams actually get this wrong

Takeaway

Structured logging: why print statements do not scale past one service

What "unstructured" actually costs you

What structured logging looks like instead

The fields that matter most

Doing it in code

The requestId is what makes multi-service logs useful

What to avoid

Takeaway

Postgres connection pooling: why your app runs out of connections under load

What a connection actually costs

Why apps blow through it so fast

The pattern that causes it

The fix inside your app: an actual pool

The fix across many instances: an external pooler

Sizing it, and the tradeoff nobody mentions

Takeaway

React Server Components vs traditional SSR: what changed and why it matters

What traditional SSR actually does

What Server Components actually change

Before and after

What this actually buys you

Where this gets misused

Takeaway

Kubernetes readiness and liveness probes: what they actually protect you from

What liveness actually does

What readiness actually does

The mistake that causes the most damage

What each check should actually look like

Tuning that actually matters

Takeaway

Self-hosting open source is easy. Running it in production is not.

The work that is not in the README

The two options most teams settle for

What Elestio actually does

Getting started takes minutes, not a sprint

Takeaway

Multi-stage Docker builds: ship the artifact, not the build shop

What ends up in a single stage image

The multi-stage pattern

Get these four details right

Name your stages

Do not copy node_modules across stages

Order instructions so the cache survives

Go smaller on the final base

The same feature, other uses

What this looks like in numbers

Takeaway

The `requestId` is what makes multi-service logs useful