{"id":368,"date":"2026-06-25T13:01:49","date_gmt":"2026-06-25T13:01:49","guid":{"rendered":"https:\/\/abrarqasim.com\/blog\/docker-best-practices-2026-dockerfile-habits-i-finally-killed\/"},"modified":"2026-06-25T13:01:49","modified_gmt":"2026-06-25T13:01:49","slug":"docker-best-practices-2026-dockerfile-habits-i-finally-killed","status":"publish","type":"post","link":"https:\/\/abrarqasim.com\/blog\/docker-best-practices-2026-dockerfile-habits-i-finally-killed\/","title":{"rendered":"Docker Best Practices 2026: The Dockerfile Habits I Finally Killed"},"content":{"rendered":"

Okay, confession time: until about eight months ago, my Dockerfiles were embarrassing. The kind of thing I’d write, ship to staging, and quietly pray nobody from the platform team would cat<\/code> them. They worked. They were also bloated, slow to build, and running as root.<\/p>\n

What changed wasn’t a new tool. It was a long Tuesday afternoon where a colleague pulled up one of my images, ran docker history<\/code> on it, and asked, very politely, why a Node.js API needed 1.4 GB of base image and a full apt cache. I had no answer. I went home and read the Docker BuildKit docs that night. This post is what I should have done years ago.<\/p>\n

If you ship containers and you’ve been copy-pasting the same Dockerfile shape since 2021, this is for you. None of this is exotic. It’s the stuff I should have been doing the whole time.<\/p>\n

Picking the right base image (stop reaching for ubuntu:latest<\/code>)<\/h2>\n

The first habit I killed was using full distro base images out of inertia. ubuntu:latest<\/code> is over 75 MB compressed before you install anything. Add Node, your app, npm cache leftovers, and you’re looking at 1 GB+ images for what is essentially a 50-line HTTP server.<\/p>\n

What I do now: start from the smallest base that actually works for the runtime. For Node, that’s node:22-alpine<\/code> (about 50 MB) or, if I want glibc, node:22-slim<\/code>. For Go binaries, gcr.io\/distroless\/static-debian12<\/code> is around 2 MB. For Python, python:3.13-slim<\/code>.<\/p>\n

Here’s the before:<\/p>\n

FROM ubuntu:24.04\nRUN apt-get update && apt-get install -y nodejs npm\nWORKDIR \/app\nCOPY . .\nRUN npm install\nCMD ["node", "server.js"]\n<\/code><\/pre>\n
After:<\/p>\n
FROM node:22-alpine\nWORKDIR \/app\nCOPY package*.json .\/\nRUN npm ci --omit=dev\nCOPY . .\nCMD ["node", "server.js"]\n<\/code><\/pre>\n
That swap alone took one of my images from 1.2 GB to about 180 MB. The Docker docs have a good page on choosing a base image<\/a> that I wish I’d read sooner.<\/p>\n
One caveat I had to learn the hard way: Alpine uses musl, not glibc. If your app pulls in a native module compiled against glibc (looking at you, certain Node native deps), you’ll get cryptic runtime errors. When that bites, fall back to -slim<\/code> rather than fighting it.<\/p>\n
Multi-stage builds for anything compiled<\/h2>\n
The second habit was shipping build tools into production. If you have a step like npm install<\/code>, cargo build<\/code>, or go build<\/code> in the same stage as your final image, you’re paying for compilers and source files at runtime forever.<\/p>\n
Multi-stage builds fix this in maybe ten extra lines. Build everything in a fat builder stage, copy the artifact into a clean final stage, ship the final stage. Here’s a Go example I use:<\/p>\n
# Builder\nFROM golang:1.23-alpine AS builder\nWORKDIR \/src\nCOPY go.mod go.sum .\/\nRUN go mod download\nCOPY . .\nRUN CGO_ENABLED=0 go build -ldflags="-s -w" -o \/out\/app .\/cmd\/api\n\n# Runtime\nFROM gcr.io\/distroless\/static-debian12\nCOPY --from=builder \/out\/app \/app\nUSER nonroot:nonroot\nENTRYPOINT ["\/app"]\n<\/code><\/pre>\n
The final image is about 8 MB. No shell, no package manager, no compiler. That last bit also matters for security, not only size. If there’s no sh<\/code>, an attacker who pops your container can’t drop into a shell. The distroless project<\/a> is run by Google and is what I reach for whenever I’m shipping a compiled binary.<\/p>\n
I held off on distroless for a while because I was scared of debugging. The trick: there’s a :debug<\/code> variant of each distroless image that includes a busybox shell. Use it for triage, then switch back.<\/p>\n
Cache mounts and .dockerignore<\/code> (the boring CI wins)<\/h2>\n
Once builds got smaller, I noticed they were still slow on CI. The culprit was usually the same: I was copying my entire repo into the build context, which busted layer caching every time a README changed.<\/p>\n
Two fixes, both boring, both huge.<\/p>\n
First, write a real .dockerignore<\/code>. Mine for a typical Node project now looks like:<\/p>\n
node_modules\n.git\n.env\n.env.*\n*.log\ncoverage\/\n.next\/cache\n.vscode\n.idea\nREADME.md\n<\/code><\/pre>\n
That alone shaved 40 seconds off my cold builds because Docker stopped uploading my local node_modules<\/code> into the context.<\/p>\n
Second, use BuildKit cache mounts for package managers. This is the single feature I wish I’d known about two years earlier:<\/p>\n
# syntax=docker\/dockerfile:1.7\nFROM node:22-alpine\nWORKDIR \/app\nCOPY package*.json .\/\nRUN --mount=type=cache,target=\/root\/.npm \\\n    npm ci --omit=dev\nCOPY . .\nCMD ["node", "server.js"]\n<\/code><\/pre>\n
The --mount=type=cache<\/code> line tells BuildKit to keep npm<\/code>’s cache between builds, even across CI runners that share the cache backend. My CI install step went from 90 seconds to about 12. There’s a BuildKit cache optimisation page<\/a> that covers this and the related --mount=type=bind<\/code> for read-only sources.<\/p>\n
Stop running as root<\/h2>\n
This was the habit I felt worst about once I noticed it. By default, processes in a container run as root. If your app gets popped, the attacker has root inside the container, which is not as bad as root on the host but still much worse than necessary.<\/p>\n
Switch to a non-root user. Most official images already give you one:<\/p>\n
FROM node:22-alpine\nWORKDIR \/app\nCOPY --chown=node:node package*.json .\/\nRUN npm ci --omit=dev\nCOPY --chown=node:node . .\nUSER node\nCMD ["node", "server.js"]\n<\/code><\/pre>\n
The node<\/code> user ships in the Node Alpine images. For your own images, add a user explicitly:<\/p>\n
RUN addgroup -S app && adduser -S app -G app\nUSER app\n<\/code><\/pre>\n
This is a one-line change that closes a real security gap, and I cannot defend why I waited so long to make it standard. The same rule I follow when I’m picking infrastructure defaults in my work on backend systems<\/a> applies here: the secure default beats the convenient one almost every time.<\/p>\n
Pin versions, pin digests for things you care about<\/h2>\n
FROM node:latest<\/code> is convenient and wrong. Latest tags drift. A reproducible build means the same Dockerfile produces the same image six months from now.<\/p>\n
At minimum, pin to a major version:<\/p>\n
FROM node:22-alpine\n<\/code><\/pre>\n
For anything sensitive, pin the image digest:<\/p>\n
FROM node:22-alpine@sha256:abc123...\n<\/code><\/pre>\n
Yes, it’s ugly. Yes, it means you have to update digests when you bump versions. Renovate and Dependabot both handle this automatically now. The payoff is that a CVE landing in a base image doesn’t silently make its way into your prod build on the next deploy.<\/p>\n
CMD<\/code> vs ENTRYPOINT<\/code> (and why I now mostly use ENTRYPOINT<\/code>)<\/h2>\n
For a long time I used CMD<\/code> for everything and never thought about it. Then a colleague ran docker run myimage --debug<\/code> and was surprised when --debug<\/code> replaced the whole command. That’s because CMD<\/code> is the default command and gets clobbered by anything you pass to docker run<\/code>.<\/p>\n
ENTRYPOINT<\/code> is the binary you always want to run. CMD<\/code> is the default arguments. If you write:<\/p>\n
ENTRYPOINT ["node", "server.js"]\nCMD ["--port=3000"]\n<\/code><\/pre>\n
then docker run myimage<\/code> runs node server.js --port=3000<\/code>, and docker run myimage --port=4000<\/code> runs node server.js --port=4000<\/code>. That’s almost always what I actually want. There’s a decent summary in the official Dockerfile reference<\/a> if you want the full interaction table.<\/p>\n
Healthchecks that actually mean something<\/h2>\n
I used to skip healthchecks because they felt like ceremony. Then I had an outage where my container was running but the app was deadlocked on a database connection, and the orchestrator happily kept routing traffic to it. A HEALTHCHECK<\/code> would have caught it.<\/p>\n
HEALTHCHECK --interval=30s --timeout=3s --start-period=10s \\\n  CMD wget --quiet --tries=1 --spider http:\/\/localhost:3000\/healthz || exit 1\n<\/code><\/pre>\n
The trick is that the healthcheck endpoint should actually exercise the thing you care about. A \/healthz<\/code> that returns 200 OK<\/code> whether the database is connected or not is lying to your orchestrator. Mine does a cheap query against the primary connection pool and a Redis ping.<\/p>\n
What’s still on my list<\/h2>\n
I’m not done. Two things I’m working on next.<\/p>\n
First, moving more of my Compose files toward production-grade defaults. I covered some of this thinking in my post on when I finally switched from pgbouncer to pgcat<\/a>, and the same instinct applies: stop trusting defaults that were written for the easy case.<\/p>\n
Second, image signing with cosign. I have it set up on one project and it works fine, but I haven’t made it standard yet. That’s the next habit to add, not kill.<\/p>\n
What to do this week<\/h2>\n
Pick one image you maintain. Run:<\/p>\n
docker history <image>\ndocker images <image> --format "{{.Size}}"\n<\/code><\/pre>\n
If the image is over 200 MB for a typical web app, switch to a smaller base. If the final stage contains compilers, add a multi-stage split. If your CI install step takes longer than 30 seconds on a warm cache, add a --mount=type=cache<\/code>. Pick one. Ship it Friday. That’s how I worked through the list above, and it’s the only way I’d recommend to anyone else.<\/p>\n","protected":false},"excerpt":{"rendered":"
Seven Dockerfile habits I changed after my images got embarrassing: smaller bases, multi-stage builds, cache mounts, non-root users, and pinned digests.<\/p>\n","protected":false},"author":2,"featured_media":367,"comment_status":"","ping_status":"open","sticky":false,"template":"","format":"standard","meta":{"rank_math_title":"","rank_math_description":"Seven Dockerfile habits I changed after my images got embarrassing: smaller bases, multi-stage builds, cache mounts, non-root users, and pinned digests.","rank_math_focus_keyword":"docker best practices","rank_math_canonical_url":"","rank_math_robots":"","footnotes":""},"categories":[302],"tags":[128,127,80,125,126],"class_list":["post-368","post","type-post","status-publish","format-standard","has-post-thumbnail","hentry","category-devops","tag-buildkit","tag-containers","tag-devops","tag-docker","tag-dockerfile"],"_links":{"self":[{"href":"https:\/\/abrarqasim.com\/blog\/wp-json\/wp\/v2\/posts\/368","targetHints":{"allow":["GET"]}}],"collection":[{"href":"https:\/\/abrarqasim.com\/blog\/wp-json\/wp\/v2\/posts"}],"about":[{"href":"https:\/\/abrarqasim.com\/blog\/wp-json\/wp\/v2\/types\/post"}],"author":[{"embeddable":true,"href":"https:\/\/abrarqasim.com\/blog\/wp-json\/wp\/v2\/users\/2"}],"replies":[{"embeddable":true,"href":"https:\/\/abrarqasim.com\/blog\/wp-json\/wp\/v2\/comments?post=368"}],"version-history":[{"count":0,"href":"https:\/\/abrarqasim.com\/blog\/wp-json\/wp\/v2\/posts\/368\/revisions"}],"wp:featuredmedia":[{"embeddable":true,"href":"https:\/\/abrarqasim.com\/blog\/wp-json\/wp\/v2\/media\/367"}],"wp:attachment":[{"href":"https:\/\/abrarqasim.com\/blog\/wp-json\/wp\/v2\/media?parent=368"}],"wp:term":[{"taxonomy":"category","embeddable":true,"href":"https:\/\/abrarqasim.com\/blog\/wp-json\/wp\/v2\/categories?post=368"},{"taxonomy":"post_tag","embeddable":true,"href":"https:\/\/abrarqasim.com\/blog\/wp-json\/wp\/v2\/tags?post=368"}],"curies":[{"name":"wp","href":"https:\/\/api.w.org\/{rel}","templated":true}]}}