Proposal: Dockerfile Guidelines

[grayside]

Description

Add Dockerfile guidelines to the samples style guide. This could be done as a new section of the guide or a separate page, because we expect little to no rules overlap.

Example guidelines include:

• Use version tags for base docker images down to the minor version (golang:1.12)
• Use alpine or debian slim base images where there is a choice
• Use WORKDIR instead of RUN mkdir
• Use WORKDIR instead of RUN cd
• Use absolute paths with WORKDIR to keep the reader oriented
• Use WORKDIR to set the working directory instead of referencing a path multiple times
• Prefer . to specific paths unless copying directories
• Add code and write output to a dedicated workspace such as /code, /app, or /build. Use the root directory / only for binaries.
• Prefer COPY to ADD unless extracting an archive or adding a remote file.
• Use ENTRYPOINT for background setup activities, use CMD for the foreground task
• End the file on ENTRYPOINT and CMD (if present) so the last lines leave a clear sense of the default behavior
• If using multi-stage builds, name all stages except optionally the final one. "builder" for a build stage, etc. Link to the multi-stage build reference documentation.
• Cloud Run: Do not include EXPOSE statement and do not set $PORT environment variable. The port is assigned at runtime. Including these in the Dockerfile has confused some developers into thinking this mechanism can control the runtime port.

Impact

This change will make sample Dockerfiles more consistent, set up some extensible practices for developers, and streamline troubleshooting of samples with Dockerfiles where teaching advanced Dockerfile syntax isn't the sample goal.

Challenge

TBD

[grayside]

We might also consider a canonical Dockerfile template starting place per language, but that doesn't replace having a set of guidelines.

Question: Dockerfile in samples style guide vs. separate page on Containerizing?