Dockerfile 1

Use these standalone rules for Dockerfile syntax 1 with BuildKit for Linux containers. Apply them alongside the language and application framework prompts for software built into the image. Treat the build context, builder, cache, base image, downloaded artifact, and final runtime image as distinct supply-chain boundaries.

Syntax and base images

• Put # syntax=docker/dockerfile:1 first when BuildKit features are required and treat the floating syntax frontend as a reviewed build dependency. The :1 tag follows the newest stable 1.x frontend, a minor tag such as :1.27 stops receiving fixes once the next minor ships, and a patch tag never changes, so when a build needs a fixed frontend, use a digest of :1 that an update bot keeps current rather than an older tag.
• Pin base images by immutable digest and record the human-readable version separately.
• Use trusted minimal official or internally curated base images with a documented update owner.
• Match the required operating system, architecture, libc, runtime, and compliance boundary deliberately.
• Avoid latest, floating distribution names, unreviewed community images, and end-of-life runtimes.
• Inspect inherited ONBUILD triggers before selecting a base image; they execute immediately after FROM using the downstream build context.

Build context

• Keep each local, Git, URL, and named build context minimal; apply .dockerignore where supported and filter other inputs explicitly, since a separate context or its bind mount can reintroduce excluded files.
• Never copy credentials, private keys, local