Docker

Docker images

An image is a build artifact with a filesystem attached. Most of what goes wrong with one is decided by the order of a dozen lines: what got cached, what got copied in that should not have been, and what the container is running as when it starts.

A built image is not a running service. "The build succeeded" says the layers assembled, nothing about whether the thing inside starts, serves, or shuts down.

When this fires

A Dockerfile is being written, changed, or reviewed; a build is slow or gives different results on different machines; an image is unexpectedly large; or config and credentials need a route into the container. It does not fire for scheduling, networking between services, or a bug in the application code that happens to be containerized.

Procedure

1. Read what exists first — the Dockerfile, .dockerignore, and how the image is actually

built (locally, in CI, with what build args). Most "write me a Dockerfile" tasks are really a fix to the one already there, and a second parallel Dockerfile is how two images drift.

1. Choose the base deliberately and pin it. Prefer the language's official image or a slim

variant; pin to a digest when reproducibility matters, because a tag moves under you. Alpine and other musl-based images are smaller but are a different libc: native extensions, DNS behaviour, and timezone handling can all differ from what you tested on. Take the smaller base only when you have run the app on it.

1. Write .dockerignore before you build. Without one, the build context carries .git,

node_modules, local env files, and build output to the daemon on every build — slow, and the direct cause of a credential ending up inside an image after a broad copy.

1. Order instructions by rate of change, slowest first: system packages, then dependency

manifests plus the install, then application source last. Copy the manifest and lockfile alone before the source, so a source edit does not invalidate the dependency layer. Any instruction invalidates every layer after it — this ordering is the whole of build caching.

1. Use a multi-stage build so compilers, dev dependencies, and test tooling never reach the

runtime image. Build in one stage, copy only the produced artifact into a clean runtime stage. This is usually the single largest size reduction available, and it shrinks the attack surface at the same time.

1. Keep secrets out of the image entirely. A build argument or environment variable set at

build time is recorded in image metadata. Copying a secret in and deleting it later does not remove it — the earlier layer still holds it. Use BuildKit's build-time secret mounts, or fetch the credential at runtime. If a secret was ever baked into an image that has been pushed anywhere, that is a leaked credential: stop, say so plainly, and treat rotation as the fix.

1. Install packages in one layer and clean up in the same instruction. Splitting the index

update from the install lets a stale cached index install stale packages; leaving package manager caches behind inflates the layer permanently, because deleting them later only adds another layer. Use a build cache mount for package caches you want to reuse across builds.

1. Run as a non-root user. Create the user, give it ownership of only the paths it must write,

and set USER before the entrypoint. Containers run as root by default and almost nothing needs it. If the process must bind a low port, change the port rather than keeping root.

1. Get PID 1 right. Use the exec form of the entrypoint and command so your process is PID 1

and receives signals directly. In shell form the shell is PID 1, SIGTERM is not forwarded, and the container is killed hard after the grace period — no graceful shutdown, no connection draining, and it looks fine locally. Add a minimal init process when the app spawns children it does not reap.

1. Take configuration at run time, not build time. An image that bakes in an environment's

URLs or feature flags is one image per environment, which breaks build-once-promote: what you tested is not what you ship. Bake only what is genuinely invariant.

1. Build it, then look at it. Build clean, then build again unchanged and confirm the cache

behaves as the ordering predicts. Inspect the layer sizes and the final size against the previous one. Then run it: confirm it starts, serves a real request, exits within a second or two on SIGTERM, and does so as the non-root user.

1. Scan before it goes anywhere, and stop there. Pushing to a registry, moving a shared tag

such as latest, and pruning images or volumes on a machine you do not own are all outward or destructive: prepare them, say exactly what would be pushed or removed, and ask.

Checklist

• [ ] .dockerignore exists and excludes VCS, local dependencies, env files, and build output
• [ ] Base image pinned; its libc is one the application has actually run on
• [ ] Dependency install sits above the source copy, and a source edit reuses it
• [ ] Build tooling exists only in a build stage, not in the runtime image
• [ ] No secret in a build arg, an env var, or any layer — checked, not assumed
• [ ] Explicit non-root USER, with ownership of the paths it writes
• [ ] Exec-form entrypoint; container observed exiting promptly on SIGTERM
• [ ] Environment-specific config supplied at run time
• [ ] Image built, run, and exercised — not just built

Failure handling

• The cache never hits. Something high in the file changes every build: a broad COPY above

the dependency install, a timestamp or commit SHA in an early build arg, or a missing .dockerignore letting the context differ each time. Find the first layer that rebuilds; the cause is at or above it.

• It works locally and fails in CI. Suspect, in order: an unpinned base tag that moved, a file

present locally but ignored or absent in the CI context, a different architecture, and build args supplied in one place only. Compare the two build contexts before changing the Dockerfile.

• The image is still huge after a multi-stage build. Layer size, not final content, is what

counts: a file added and removed in a later instruction is still carried. Look at per-layer sizes and find the fat one rather than guessing.

• The container exits immediately. Read its logs before editing anything. A foreground process

that backgrounds itself, a missing runtime dependency dropped between stages, and a permission error after adding USER all present the same way.

• No way to build or run here. Say the image was written but never built, and never describe it

as working. A Dockerfile that has not been built is a draft.

Evidence to report

The final image size and how it compares to before. The result of the second, unchanged build — which layers were cached. What the container did when run: startup, one real request served, and the observed shutdown on SIGTERM. The user id the process runs as. Scanner findings, with severities, or a statement that no scan was run. And what was not checked — other architectures, other environments, and registry push, if the push has not happened.

Source & license

This open-source skill is cataloged on AgentStack and links to its original source — we do not rehost the code.

• Author: nahid-sparktales
• Source: nahid-sparktales/agent-dispatcher
• License: MIT

Install and usage instructions live in the source repository linked above.