dockerfile

Best Practices

• Use multi-stage builds to minimize final image size (builder stage + runtime stage)
• Run as non-root user in the final stage (adduser/addgroup + USER directive)
• Pin base image versions with specific tags (never use :latest in production)
• Order instructions for optimal layer caching — copy dependency files before source code
• Minimize number of layers by combining related RUN commands with &&
• Include HEALTHCHECK for production images with appropriate interval and timeout
• Never embed secrets, credentials, or API keys in the image (use build args or runtime env)
• Copy dependency manifest first (package.json, requirements.txt, go.mod) for layer caching
• Use .dockerignore to exclude unnecessary files from build context
• Set WORKDIR before COPY/RUN commands
• Use COPY instead of ADD unless extracting archives
• Set appropriate EXPOSE for documented ports
• Use ENTRYPOINT for the main process, CMD for default arguments
• For compiled languages, use scratch or distroless as final base for minimal attack surface
• REQUIRED inline comments. Prefix each stage with a `# ── stage <name> ─` banner describing its role. Add a short `#` comment above every non-trivial COPY, RUN, ENV, USER, HEALTHCHECK, and ENTRYPOINT line explaining why it is there (layer caching, security, runtime config). Comments must be specific — no generic filler like `# install dependencies`.