Writing Lean Dockerfiles and Shell Entrypoints

In production environments, every megabyte in a Docker image has a cost: slower pulls, larger attack surfaces, and wasted registry storage. Lean Dockerfiles combined with robust shell entrypoints are a hallmark of mature DevOps practice.

• Multi-stage builds separate build-time tooling from the final runtime image, dramatically reducing size.
• Entrypoint shims are small shell scripts that bootstrap containers: they template config files, validate environment variables, handle signals, and finally exec the main process.
• Together they form the backbone of reliable, portable container workloads in Kubernetes, ECS, and bare-metal environments.

This lesson covers both disciplines end-to-end, with production-grade patterns you can drop directly into your pipelines.

A multi-stage Dockerfile uses multiple FROM instructions. Each stage is an isolated layer set; you copy only the artifacts you need into the next stage.

• Stage 0 (builder): installs compilers, test runners, build dependencies.
• Stage 1 (runtime): starts from a minimal base (e.g. alpine, distroless) and copies only compiled binaries or app bundles.
• The final image never contains gcc, make, or source code unless you explicitly copy them.

Use --from=<stage> in COPY to pull files across stage boundaries. Name stages with AS <name> for readability and selective targeting with docker build --target.

Every RUN, COPY, and ADD instruction creates a new layer. Poorly ordered instructions invalidate the build cache unnecessarily, making CI pipelines slow.

• Copy dependency manifests (package.json, go.mod, requirements.txt) before copying source code so dependency installation is cached independently.
• Chain related commands with && and clean up in the same RUN layer to avoid leaving package cache in intermediate layers.
• Use --no-cache in package managers and remove list files after install.

Private registries, SSH keys, and API tokens must never appear in image layers. Docker BuildKit provides two safe mechanisms:

• --secret: mounts a secret file inside a single RUN step without baking it into a layer. Access via /run/secrets/<id>.
• --ssh: forwards the host SSH agent socket into the build so git clone can authenticate without embedding private keys.

Enable BuildKit with DOCKER_BUILDKIT=1 or via docker buildx build. The # syntax=docker/dockerfile:1 directive unlocks these features.

The entrypoint shim is a shell script set as ENTRYPOINT in the Dockerfile. Its job is to prepare the runtime environment before handing control to the main process.

A well-structured shim follows this order:

• Step 1: Set set -euo pipefail so any failure aborts early.
• Step 2: Validate required environment variables and fail fast with a helpful message.
• Step 3: Template configuration files from environment variables.
• Step 4: Register signal handlers for graceful shutdown.
• Step 5: exec "$@" — replace the shell with the main process so PID 1 is the application, not the shim.

The final exec is critical: without it, signals sent by Kubernetes or the Docker runtime are not forwarded to the child process.

envsubst (from the GNU gettext package, present in Alpine as gettext) substitutes ${VAR} placeholders in a template file with their current environment variable values.

• Ship a *.tmpl config template in the image; the entrypoint renders it at startup.
• Pass the variable list explicitly to envsubst so it does not accidentally expand unrelated dollar signs (e.g. in nginx regex).
• Write the rendered file to a writable path like /tmp or a dedicated config volume.

Containers receive SIGTERM when stopped by Kubernetes, ECS, or docker stop. If your entrypoint shim is PID 1 and does not forward signals, the main process gets killed with SIGKILL after the grace period — causing dropped requests or data corruption.

• Use trap to catch SIGTERM and SIGINT in the shim.
• Forward the signal to the child PID using kill -TERM "$child".
• Use wait "$child" to block until the child exits, then propagate its exit code.
• Alternatively, use exec to replace the shell entirely — then the OS delivers signals directly to the child, no trap needed. This is the preferred pattern for simple cases.

When your container spawns child processes (e.g. a shell that forks workers), you need a real init to reap zombie processes. tini is a tiny init binary purpose-built for containers.

• Add tini to your image and set it as the entrypoint wrapper.
• It reaps zombie children, forwards signals correctly, and exits with the child's status code.
• Docker ships a built-in tini activated with docker run --init, but embedding it in the image ensures the behaviour is consistent across runtimes (Kubernetes, ECS, etc.).

Containers that run as root (UID 0) are a major security risk: a container escape grants full host access. Always drop to an unprivileged user before executing the main process.

• Create a dedicated system user and group in the Dockerfile with addgroup / adduser (Alpine) or groupadd / useradd (Debian).
• Change ownership of app files with COPY --chown=appuser:appgroup — more efficient than a separate RUN chown layer.
• Switch to the user with the USER instruction. The entrypoint and CMD inherit this user.
• Kubernetes securityContext.runAsNonRoot: true will refuse to start an image that still runs as root.

Kubernetes liveness and readiness probes are defined in manifests, but you can also bake a HEALTHCHECK into the Dockerfile for standalone docker run and Docker Compose environments.

• HEALTHCHECK --interval=10s --timeout=3s --start-period=15s --retries=3 CMD ...
• Use curl --fail or wget -qO- for HTTP services; for non-HTTP daemons, probe a socket with /dev/tcp/localhost/PORT.
• Install only what you need: in distroless images, avoid adding curl just for health checks — use a purpose-built probe binary or the application's own health binary.

The following is a complete, production-grade entrypoint shim combining all the patterns from this lesson: env validation, config templating, signal forwarding, and exec hand-off. This pattern is used in real-world Node.js, Python, and Go microservices deployed on Kubernetes.

• Every section is commented to serve as a self-documenting template.
• The shim is kept under 50 lines — entrypoints should be simple and auditable.
• Notice the final exec "$@": after all setup is done, the shell is replaced by the application process so it becomes PID 1 and receives all OS signals directly.

Test your understanding of signal handling in container entrypoint scripts.

You have covered the full stack of production container authoring:

• Multi-stage builds use multiple FROM instructions to keep compilers and build tools out of the final image, producing lean, minimal runtime layers.
• Layer ordering — copy dependency manifests before source code — maximises cache hits and speeds up CI pipelines.
• BuildKit secrets and SSH mounts keep credentials out of image history without breaking authenticated builds.
• Entrypoint shims validate environment variables, template config files with envsubst, and hand off to the application via exec "$@".
• Signal handling requires either exec (so the app is PID 1) or an explicit trap + kill + wait pattern when background jobs are used.
• tini adds zombie reaping and correct signal forwarding when the container spawns multiple processes.
• Non-root users and HEALTHCHECK instructions complete a secure, observable image ready for Kubernetes production workloads.

Combine these patterns consistently and your images will be smaller, faster to deploy, and significantly more robust under production conditions.