From a6a470e4e906ecd8ec82193416970fe1df4154ad Mon Sep 17 00:00:00 2001 From: Sebastiaan van Stijn Date: Thu, 20 Feb 2020 11:01:32 +0100 Subject: [PATCH 1/3] Dockerfile: use "from scratch" image to collect archives Signed-off-by: Sebastiaan van Stijn --- Dockerfile | 39 ++++++++++++++++++--------------------- 1 file changed, 18 insertions(+), 21 deletions(-) diff --git a/Dockerfile b/Dockerfile index 07e4dec0e3..17f5934e4e 100644 --- a/Dockerfile +++ b/Dockerfile @@ -52,17 +52,18 @@ COPY --from=docs/docker.github.io:nginx-onbuild /etc/nginx/conf.d/default.conf / CMD echo -e "Docker docs are viewable at:\nhttp://0.0.0.0:4000"; exec nginx -g 'daemon off;' -# Build the archived docs -# these docs barely change, so can be cached -FROM deploybase AS archives -# Get all the archive static HTML and put it into place. 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:v17.03 ${TARGET} ${TARGET} -COPY --from=docs/docker.github.io:v17.06 ${TARGET} ${TARGET} -COPY --from=docs/docker.github.io:v17.09 ${TARGET} ${TARGET} -COPY --from=docs/docker.github.io:v17.12 ${TARGET} ${TARGET} -COPY --from=docs/docker.github.io:v18.03 ${TARGET} ${TARGET} -COPY --from=docs/docker.github.io:v18.09 ${TARGET} ${TARGET} +# Stage with static HTML for all archives +FROM scratch AS archives +ENV TARGET=/usr/share/nginx/html +# To add a new archive, add it here and ALSO edit _data/docsarchive/archives.yaml +# to add it to the drop-down +COPY --from=docs/docker.github.io:v17.03 ${TARGET} / +COPY --from=docs/docker.github.io:v17.06 ${TARGET} / +COPY --from=docs/docker.github.io:v17.09 ${TARGET} / +COPY --from=docs/docker.github.io:v17.12 ${TARGET} / +COPY --from=docs/docker.github.io:v18.03 ${TARGET} / +COPY --from=docs/docker.github.io:v18.09 ${TARGET} / + # Fetch upstream resources (reference documentation) # Only add the files that are needed to build these reference docs, so that @@ -74,20 +75,16 @@ COPY ./_data/toc.yaml ./_data/ RUN bash ./_scripts/fetch-upstream-resources.sh . -# Build the current docs from the checked out branch +# Build the static HTML for the current docs. +# After building with jekyll, fix up some links, but don't touch the archives FROM builderbase AS current COPY . . COPY --from=upstream-resources /usr/src/app/md_source/. ./ - -# Build the static HTML, now that everything is in place RUN jekyll build -d ${TARGET} - -# Fix up some links, don't touch the archives 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 -# Docs with archives (for deploy) -FROM archives AS deploy - -# Add the current version of the docs -COPY --from=current ${TARGET} ${TARGET} +# Final stage, which includes nginx, current docs, and archived versions +FROM deploybase AS deploy +COPY --from=archives / ${TARGET} +COPY --from=current ${TARGET} ${TARGET} From 136a8d3f964813a1994996805ee799ceaf2c2e38 Mon Sep 17 00:00:00 2001 From: Sebastiaan van Stijn Date: Thu, 20 Feb 2020 15:30:25 +0100 Subject: [PATCH 2/3] Dockerfile: allow building docs without archives This adds a `ENABLE_ARCHIVES` build-arg, which allows building the documentation without archives. Note that currently, the archives drop-down is still added unconditionally (so also included if archives are disabled). Signed-off-by: Sebastiaan van Stijn --- Dockerfile | 21 ++++++++++++++++++--- 1 file changed, 18 insertions(+), 3 deletions(-) diff --git a/Dockerfile b/Dockerfile index 17f5934e4e..4b8d882a07 100644 --- a/Dockerfile +++ b/Dockerfile @@ -18,6 +18,8 @@ ARG ENGINE_BRANCH="19.03.x" # Distribution ARG DISTRIBUTION_BRANCH="release/2.7" +# Set to "false" to build the documentation without archives +ARG ENABLE_ARCHIVES=true ### # Set up base stages for building and deploying @@ -52,8 +54,11 @@ COPY --from=docs/docker.github.io:nginx-onbuild /etc/nginx/conf.d/default.conf / CMD echo -e "Docker docs are viewable at:\nhttp://0.0.0.0:4000"; exec nginx -g 'daemon off;' -# Stage with static HTML for all archives -FROM scratch AS archives +# Empty stage if archives are disabled (ENABLE_ARCHIVES=false) +FROM scratch AS archives-false + +# Stage with static HTML for all archives (ENABLE_ARCHIVES=true) +FROM scratch AS archives-true ENV TARGET=/usr/share/nginx/html # To add a new archive, add it here and ALSO edit _data/docsarchive/archives.yaml # to add it to the drop-down @@ -64,6 +69,8 @@ COPY --from=docs/docker.github.io:v17.12 ${TARGET} / COPY --from=docs/docker.github.io:v18.03 ${TARGET} / COPY --from=docs/docker.github.io:v18.09 ${TARGET} / +# Stage either with, or without archives, depending on ENABLE_ARCHIVES +FROM archives-${ENABLE_ARCHIVES} AS archives # Fetch upstream resources (reference documentation) # Only add the files that are needed to build these reference docs, so that @@ -84,7 +91,15 @@ RUN jekyll build -d ${TARGET} 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 -# Final stage, which includes nginx, current docs, and archived versions +# Final stage, which includes nginx, and, depending on ENABLE_ARCHIVES, either +# current docs and archived versions (ENABLE_ARCHIVES=true), or only the current +# docs (ENABLE_ARCHIVES=false). +# +# To build current docs, including archives: +# DOCKER_BUILDKIT=1 docker build -t docs . +# +# To build without archives: +# DOCKER_BUILDKIT=1 docker build -t docs --build-arg ENABLE_ARCHIVES=false . FROM deploybase AS deploy COPY --from=archives / ${TARGET} COPY --from=current ${TARGET} ${TARGET} From c8b335c3b81400dfd9fd50392327ddeee3fc977c Mon Sep 17 00:00:00 2001 From: Sebastiaan van Stijn Date: Fri, 21 Feb 2020 10:44:25 +0100 Subject: [PATCH 3/3] Dockerfile: add target to output the generated HTML This patch adds a stage that only contains the generated files. It can be used to export the generated HTML for hosting the documentation on a non-containerised service (e.g. to deploy to an s3 bucket). When using BuildKit, use the `--output` option to build the files and to copy them to your local filesystem. For example, to build current docs, including archives: DOCKER_BUILDKIT=1 docker build --target=deploy-source --output=./_site . And to build without archives: DOCKER_BUILDKIT=1 docker build --target=deploy-source --build-arg ENABLE_ARCHIVES=false --output=./_site . Signed-off-by: Sebastiaan van Stijn --- Dockerfile | 17 +++++++++++++++-- 1 file changed, 15 insertions(+), 2 deletions(-) diff --git a/Dockerfile b/Dockerfile index 4b8d882a07..ee0d6860d7 100644 --- a/Dockerfile +++ b/Dockerfile @@ -91,6 +91,19 @@ RUN jekyll build -d ${TARGET} 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 +# This stage only contains the generated files. It can be used to host the +# documentation on a non-containerised service (e.g. to deploy to an s3 bucket). +# When using BuildKit, use the '--output' option to build the files and to copy +# them to your local filesystem. +# +# To build current docs, including archives: +# DOCKER_BUILDKIT=1 docker build --target=deploy-source --output=./_site . +# +# To build without archives: +# DOCKER_BUILDKIT=1 docker build --target=deploy-source --build-arg ENABLE_ARCHIVES=false --output=./_site . +FROM archives AS deploy-source +COPY --from=current /usr/share/nginx/html / + # Final stage, which includes nginx, and, depending on ENABLE_ARCHIVES, either # current docs and archived versions (ENABLE_ARCHIVES=true), or only the current # docs (ENABLE_ARCHIVES=false). @@ -101,5 +114,5 @@ RUN find ${TARGET} -type f -name '*.html' | grep -vE "v[0-9]+\." | while read i; # To build without archives: # DOCKER_BUILDKIT=1 docker build -t docs --build-arg ENABLE_ARCHIVES=false . FROM deploybase AS deploy -COPY --from=archives / ${TARGET} -COPY --from=current ${TARGET} ${TARGET} +WORKDIR $TARGET +COPY --from=deploy-source / .