Dockerfiles that Age Well. Containers from a practitioner’s perspective with timeless lessons for Dockerfile best practices, smaller Docker images, and reliable production containers.
I was on a late Friday, coffee cooling on the desk, staring at a build that worked on my laptop and exploded on a tiny VPS. The only thing that changed was the base image tag. Same Dockerfile, different results. The app shouted at a missing C library that yesterday was there and today was gone. That is when it clicked. My container was modern, but my Dockerfile was fragile. If the ground keeps shifting, you do not build a higher tower. You pour a better foundation.
The goal: Dockerfiles that keep working
We are all riding the wave. Docker went stable, fig is getting real traction for local dev, and every week someone ships a fresh base image on the registry. There is energy and also churn. A Dockerfile that feels fine today can turn flaky tomorrow. The trick is writing it so your build is boring six months from now. Boring is good.
Technical muscle: patterns that last
1. Pin what you can
Pick a specific base image tag. Use ubuntu colon 14.04 or centos colon 6 instead of latest. Version your language runtimes, system packages, and tools. When you download a tarball, save the checksum and verify it. Floating tags make your build look fresh while quietly changing under your feet. Predictable beats surprising.
2. Respect the build cache
Order instructions from least to most likely to change. Put system setup and package installs first, then app dependencies, then your source. This keeps the Docker build cache effective and your builds fast. When you combine commands, do it with care. A giant RUN line is not magic. Keep it readable and stable, but avoid steps that invalidate the cache for no reason.
3. Update and install in the same layer
If you are using apt, run update and install together so you do not use a stale index. Clean up package lists in the same step. RPM users should think the same way. The goal is a smaller Docker image size and fewer surprises. Temporary build artifacts have no place in the final image.
4. One main process
Run one clear process in the foreground. That keeps logs simple and shutdown signals clean. If you need more processes, consider multiple containers linked together. It is tempting to run a process manager inside the container, but it makes the story messy. The container is your unit of behavior. Keep it focused.
5. ENTRYPOINT and CMD with purpose
Use the exec form so signals reach the process. Set ENTRYPOINT for the program and CMD for default args. That gives you a steady command line that can still be tuned at runtime. This tiny detail makes shutdowns cleaner and keeps your production containers from hanging during deploys.
6. Keep secrets out
Do not bake keys into layers. Build args end up in image history. Move secrets to runtime with environment variables, mounted files, or a key service. Remember that every layer is visible. If you would not commit it to git, do not bake it into a layer.
7. Data lives outside
Declare volumes for mutable data. Let the container be ephemeral and the data be durable. If the app writes logs or user content, map those to a place you can back up and rotate. Containers are cattle, your data is not.
8. No SSH in containers
You do not need SSH inside the image. For debugging, attach or use nsenter while we wait for a friendlier flow to land. Opening an SSH server multiplies your surface area and drags in packages you do not want. Less is safer.
9. Be picky with base images
Small is nice, but not at the cost of sanity. The official images are getting better and are maintained in the open. If you need init like behavior or sane defaults for PID 1, pick a base that solves it cleanly instead of duct tape. Busybox is tiny, Ubuntu and CentOS are friendly, and there are focused bases that handle zombies and signals.
10. ONBUILD for builder images
If you publish a base for your team, consider ONBUILD triggers to enforce a golden path. It helps new services inherit the right steps without copy paste. Use it carefully. Hidden magic can be confusing if you overdo it.
11. Logs to stdout and stderr
Dump logs to the standard streams, not to files inside the image. That way your platform can collect them. It also keeps images cleaner and makes local dev sane. When the process speaks to stdout, everyone can listen.
Signals for the people running teams
If you run a team, the Dockerfile is a contract. It captures build time, runtime, and ops knowledge in a tiny file. To keep your stack sharp, put guardrails around it.
– Create a curated set of base images with pinned tags and a changelog. Do not let every service pick its own adventure.
– Add a Dockerfile review to code reviews. Look for version pins, cache friendly layering, clean up steps, and a single process model.
– Run repeatable builds in CI. Never build from a developer laptop for production images. Tag by commit, store build metadata, and keep the logs.
– Set a tagging policy. Promote images from dev to staging to production by moving tags, not by rebuilding from scratch. Rebuild only on purpose.
– Watch disk pressure on build hosts. Layers stack up. Garbage collect old images with a simple schedule before they eat your machines.
– Keep a short runbook for each image. Exposed ports, volumes, required env vars, and how to update. It saves the weekend when someone new is on call.
None of this is fancy. It is craft. A little discipline in the Dockerfile saves a pile of energy later.
Your turn: make one Dockerfile future friendly
Pick one service. In the next hour, do these steps:
– Pin the base image and any package versions you can.
– Merge your package update and install into one step and clean caches.
– Make sure there is a single clear ENTRYPOINT and a sensible CMD.
– Route logs to stdout and stderr.
– Remove SSH or any debug daemons baked into the image.
– Write a brief runbook in the repo readme with ports, volumes, and env vars.
Commit, push, rebuild, and tag. You just made a Dockerfile that ages well. Tomorrow, you will ship features instead of chasing ghosts in a base layer.