Improve ordering of master Dockerfile (docker#5630)

Dockerfile

@@ -4,9 +4,10 @@
 # Here is the sequence:
 # 1.  Set up the build
 # 2.  Fetch upstream resources
-# 3.  Build master
-# 4.  Copy static HTML from already-built archive images
-# 5.  Copy Nginx config
+# 3.  Build static HTML from master
+# 4.  Reset to clean tiny nginx image
+# 5.  Copy Nginx config and archive HTML, which don't change often and can be cached
+# 6.  Copy static HTML from previous build stage (step 3)
 #
 # When the image is run, it starts Nginx and serves the docs at port 4000
 
@@ -49,16 +50,20 @@ RUN jekyll build -s ${SOURCE} -d ${TARGET} --config ${SOURCE}/_config.yml
 RUN find ${TARGET} -type f -name '*.html' | grep -vE "v[0-9]+\." | while read i; do sed -i 's#href="https://docs.docker.com/#href="/#g' "$i"; done
 
 # BUILD OF MASTER DOCS IS NOW DONE!
+
 # Reset to alpine so we don't get any docs source or extra apps
 FROM nginx:alpine
 
 # Set the target again
 ENV TARGET=/usr/share/nginx/html
 
-# Get the built docs output from the previous step
-COPY --from=builder ${TARGET} ${TARGET}
+# Get the nginx config from the nginx-onbuild image
+# This hardly ever changes so should usually be cached
+COPY --from=docs/docker.github.io:nginx-onbuild /etc/nginx/conf.d/default.conf /etc/nginx/conf.d/default.conf
 
 # Get all the archive static HTML and put it into place
+# Go oldest-to-newest to take advantage of the fact that we change older
+# archives less often than new ones.
 # To add a new archive, add it here
 # AND ALSO edit _data/docsarchives/archives.yaml to add it to the drop-down
 COPY --from=docs/docker.github.io:v1.4 ${TARGET} ${TARGET}
@@ -74,14 +79,11 @@ COPY --from=docs/docker.github.io:v1.13 ${TARGET} ${TARGET}
 COPY --from=docs/docker.github.io:v17.03 ${TARGET} ${TARGET}
 COPY --from=docs/docker.github.io:v17.06 ${TARGET} ${TARGET}
 
-# The archives are self-browseable and each come with an index.html. This creates
-# a conflict with the index.html and 404.html from the master build. The easiest
-# solution is to just overwrite them again here.
-COPY --from=builder ${TARGET}/index.html ${TARGET}/index.html
-COPY --from=builder ${TARGET}/404.html ${TARGET}/404.html
+# Get the built docs output from the previous build stage
+# This ordering means all previous layers can come from cache unless an archive
+# changes
 
-# Get the nginx config from the nginx-onbuild image
-COPY --from=docs/docker.github.io:nginx-onbuild /etc/nginx/conf.d/default.conf /etc/nginx/conf.d/default.conf
+COPY --from=builder ${TARGET} ${TARGET}
 
 # Serve the site (target), which is now all static HTML
 CMD echo -e "Docker docs are viewable at:\nhttp://0.0.0.0:4000"; exec nginx -g 'daemon off;'