{"id":139,"date":"2026-04-22T13:02:31","date_gmt":"2026-04-22T13:02:31","guid":{"rendered":"https:\/\/abrarqasim.com\/blog\/docker-best-practices-2026-what-i-actually-use\/"},"modified":"2026-04-22T13:02:31","modified_gmt":"2026-04-22T13:02:31","slug":"docker-best-practices-2026-what-i-actually-use","status":"publish","type":"post","link":"https:\/\/abrarqasim.com\/blog\/docker-best-practices-2026-what-i-actually-use\/","title":{"rendered":"Docker best practices in 2026: the ones I actually use"},"content":{"rendered":"

Okay, confession: I was going to write this post two years ago. Then I dockerized a Laravel app, watched the image balloon to 1.8 GB, and decided I wasn’t qualified to write about Docker yet. Two years and roughly a hundred Dockerfiles later, I have opinions. Not a lot of them. Most “best practices” lists read like someone paraphrased the Docker docs and added “2026” to the title. I’d rather tell you the handful of things I actually do on every project, why, and the 2020-era advice I’ve quietly stopped caring about.<\/p>\n

This is a working-developer list, not a conference talk. If you ship containers to production, some of this will be old news. Some of it should be.<\/p>\n

Multi-stage builds, with the boring layout that actually works<\/h2>\n

If you only take one thing from this post: multi-stage builds<\/a> aren’t optional. A builder stage compiles, a runtime stage copies just the artifact. The part that trips people up isn’t the pattern. It’s layering the pattern so the cache actually helps you.<\/p>\n

Here’s the template I paste into almost every Node or Go project:<\/p>\n

# --- deps stage: only changes when dependencies change\nFROM node:22-alpine AS deps\nWORKDIR \/app\nCOPY package.json package-lock.json .\/\nRUN npm ci\n\n# --- build stage: inherits cached deps\nFROM node:22-alpine AS build\nWORKDIR \/app\nCOPY --from=deps \/app\/node_modules .\/node_modules\nCOPY . .\nRUN npm run build\n\n# --- runtime stage: nothing but what production needs\nFROM node:22-alpine AS runtime\nWORKDIR \/app\nENV NODE_ENV=production\nCOPY --from=build \/app\/dist .\/dist\nCOPY --from=build \/app\/node_modules .\/node_modules\nCOPY package.json .\/\nUSER node\nCMD ["node", "dist\/index.js"]\n<\/code><\/pre>\n
Three stages, not two. The deps<\/code> stage is the point: it only rebuilds when package.json<\/code> or the lockfile changes. Your app code can change every ten seconds and the dependency layer stays cached. In a Laravel project the same shape works with composer install<\/code>. I used to inline the install step in the build stage and wonder why CI was slow. That’s why.<\/p>\n
Pin base images, but stop pinning by digest in app repos<\/h2>\n
This one I’ve gone back and forth on. The consensus advice is “pin by SHA256 digest, always.” I tried it. It made my life worse.<\/p>\n
What I do now: pin to a minor version tag (node:22.11-alpine<\/code>, not node:22-alpine<\/code> or node:22.11.0-alpine@sha256:...<\/code>). You get reproducible-enough builds and still get patch updates when you rebuild. If you need byte-exact reproducibility for compliance or audited environments, you pin digests. But then you need Dependabot digest updates<\/a> or something similar, because otherwise you’ll sit on an unpatched base image for six months and not notice.<\/p>\n
The honest answer: pick a policy per repo. A payments service I maintain pins by digest with automated PRs. A throwaway internal tool pins to :22-alpine<\/code> and rebuilds weekly via a scheduled CI job. Both are fine.<\/p>\n
Stop running as root. Actually stop.<\/h2>\n
I know this is lecture material, but I still see it in code review weekly. Every Dockerfile should end with a non-root user. Node images ship with a node<\/code> user ready to go, so it’s one line:<\/p>\n
USER node\n<\/code><\/pre>\n
For Go or Rust binaries where you control the image from scratch, create the user explicitly:<\/p>\n
FROM alpine:3.20 AS runtime\nRUN addgroup -S app && adduser -S -G app app\nCOPY --from=build --chown=app:app \/src\/target\/release\/myapp \/usr\/local\/bin\/\nUSER app\nENTRYPOINT ["myapp"]\n<\/code><\/pre>\n
The Docker security docs<\/a> cover the reasoning better than I can. If you can’t run as non-root because your app writes to \/var\/lib\/something<\/code>, fix the app, don’t skip the user. “Temporary” container permissions become permanent the moment something ships.<\/p>\n
Smaller images are a feature, not a flex<\/h2>\n
The size-obsession crowd loves posting screenshots of 8 MB Go containers. Fun, but the actual reason to care about image size is cold-start latency and pull costs on autoscaling. A 200 MB image pulled 40x a minute across a fleet is a real number on your AWS bill.<\/p>\n
What actually helps:<\/p>\n
    \n
  1. Alpine or distroless for the runtime stage.<\/strong> Alpine is fine for most things. Distroless (gcr.io\/distroless\/nodejs22-debian12<\/code>, gcr.io\/distroless\/static-debian12<\/code> for Go) is smaller and has a smaller attack surface, but you can’t docker exec -it ... sh<\/code> into it when debugging, which you will want to do eventually. Pick your trade-off. I use distroless for Go services and Alpine for Node.<\/li>\n
  2. Use .dockerignore<\/code> like you mean it.<\/strong> node_modules<\/code>, .git<\/code>, coverage\/<\/code>, *.log<\/code>, local .env<\/code> files. Every file you don’t copy is one that can’t bloat your image or leak into it. I’ve pulled AWS keys out of other people’s containers because their .dockerignore<\/code> was empty.<\/li>\n
  3. Don’t install build tooling in the runtime stage.<\/strong> No npm install -g<\/code>, no apt install build-essential<\/code>, no interactive shells. If you think you need curl to run a healthcheck, use HEALTHCHECK<\/code> with your app’s own \/health<\/code> endpoint instead.<\/li>\n<\/ol>\n
    The size flex is silly. The discipline behind the size is what matters. The Docker build best practices guide<\/a> is still the cleanest primer on this.<\/p>\n
    BuildKit features I’d have to be pried away from<\/h2>\n
    Modern Docker (buildx<\/code> \/ BuildKit) gives you two things that paid for themselves the first week.<\/p>\n
    Cache mounts<\/strong> let you cache things like ~\/.cache\/pip<\/code> or \/root\/.npm<\/code> across builds without baking them into layers:<\/p>\n
    RUN --mount=type=cache,target=\/root\/.npm \\\n    npm ci\n<\/code><\/pre>\n
    CI goes from 90 seconds of npm install to about 12. The BuildKit cache mount docs<\/a> show the syntax for pip, cargo, apt, and go. Use it everywhere.<\/p>\n
    Secret mounts<\/strong> mean you can pass an NPM_TOKEN<\/code> or a private registry key into a single RUN<\/code> step without it landing in any layer:<\/p>\n
    RUN --mount=type=secret,id=npm_token \\\n    NPM_TOKEN=$(cat \/run\/secrets\/npm_token) npm ci\n<\/code><\/pre>\n
    Pair this with DOCKER_BUILDKIT=1<\/code> (default on recent Docker versions) and build-arg passing from CI. It replaces the old pattern of copying .npmrc<\/code> in and deleting it later, which, spoiler, leaves the token in an intermediate layer anyway.<\/p>\n
    Compose files are still where real projects go sideways<\/h2>\n
    I’ve become more relaxed about Kubernetes and more particular about docker-compose.yml<\/code>. Two specific things I do now.<\/p>\n
    First, explicit healthchecks on anything another service depends on. A Postgres container with healthcheck: pg_isready<\/code> lets me use depends_on.condition: service_healthy<\/code> so my app doesn’t race the database at startup. Five lines of YAML. Has saved me more flaky CI runs than anything else.<\/p>\n
    Second, I stopped sharing a single docker-compose.yml<\/code> between local dev and production. Local gets docker-compose.yml<\/code> plus docker-compose.override.yml<\/code> (auto-merged), with bind mounts and debug ports. Production uses a docker-compose.prod.yml<\/code> composed in explicitly with -f<\/code>. Slightly more typing, and it avoids the “works on my machine, breaks in staging because of a volume mount” class of bug. I wrote a bit about keeping clean boundaries between environments in my API design notes<\/a>; the same instinct applies to infra.<\/p>\n
    Things I used to do that I’ve quietly dropped<\/h2>\n
    In the spirit of admitting things.<\/p>\n