Merge pull request #11600 from thaJeztah/prod_develop

Separate "development" and "production" configurations

.github/workflows/build-published.yml

@@ -17,7 +17,7 @@ jobs:
         run: docker version && docker info
       - uses: actions/checkout@v2
       - name: build current docs
-        run: docker build --target=deploy-source --output=./_site .
+        run: docker build --build-arg JEKYLL_ENV=production --target=deploy-source --output=./_site .
       - name: upload files to S3 bucket
         run: aws s3 sync --acl public-read _site s3://docs.docker.com-us-east-1/ --delete
         env:

Dockerfile

@@ -10,6 +10,8 @@
 #
 # When the image is run, it starts Nginx and serves the docs at port 4000
 
+# Jekyll environment (development/production)
+ARG JEKYLL_ENV=development
 
 # Engine
 ARG ENGINE_BRANCH="19.03"
@@ -53,9 +55,16 @@ COPY --from=upstream-resources /usr/src/app/md_source/. ./
 # substitute the "{site.latest_engine_api_version}" in the title for the latest
 # API docs, based on the latest_engine_api_version parameter in _config.yml
 RUN ./_scripts/update-api-toc.sh
-RUN jekyll build -d ${TARGET} \
- && find ${TARGET} -type f -name '*.html' | while read i; do sed -i 's#\(<a[^>]* href="\)https://docs.docker.com/#\1/#g' "$i"; done \
- && sed -i 's#<loc>/#<loc>https://docs.docker.com/#' "${TARGET}/sitemap.xml"
+ARG JEKYLL_ENV
+RUN echo "Building docs for ${JEKYLL_ENV} environment"
+RUN set -eux; \
+ if [ "${JEKYLL_ENV}" = "production" ]; then \
+    jekyll build -d ${TARGET} --config _config.yml,_config_production.yml; \
+ else \
+    jekyll build -d ${TARGET}; \
+ fi; \
+ find ${TARGET} -type f -name '*.html' | while read i; do sed -i 's#\(<a[^>]* href="\)https://docs.docker.com/#\1/#g' "$i"; done; \
+ sed -i 's#<loc>/#<loc>https://docs.docker.com/#' "${TARGET}/sitemap.xml";
 
 
 # This stage only contains the generated files. It can be used to host the
@@ -79,4 +88,6 @@ COPY --from=current  /usr/share/nginx/html .
 
 # Configure NGINX
 COPY _deploy/nginx/default.conf /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;'
+ARG JEKYLL_ENV
+ENV JEKYLL_ENV=${JEKYLL_ENV}
+CMD echo -e "Docker docs are viewable at:\nhttp://0.0.0.0:4000 (build target: ${JEKYLL_ENV})"; exec nginx -g 'daemon off;'

_config.yml

@@ -11,13 +11,7 @@ incremental: true
 permalink: pretty
 safe: false
 lsi: false
-exclude: ["_scripts", "tests", "apidocs/layouts", "Gemfile", "hooks", "index.html", "404.html"]
-
-# Google Analytics, etc.
-# TODO these should only be set when building for production, or passed as an environment variable when building
-google_analytics: GTM-WL2QLG5
-polldaddy_id: 8453675
-
+exclude: ["_samples", "_scripts", "404.html", "datacenter", "ee", "index.html"]
 
 # Component versions -- address like site.docker_ce_version
 # You can't have - characters in these for non-YAML reasons
@@ -121,5 +115,5 @@ defaults:
 #
 # We specify the directory for Jekyll so we can use @imports.
 sass:
-  sass_dir:          _scss
-  style:            :compressed
+  sass_dir: _scss
+  style: expanded

_config_authoring.yml

@@ -1,122 +0,0 @@
-name: Docker Documentation
-markdown: kramdown
-kramdown:
-  input: GFM
-  gfm_quirks: [paragraph_end, no_auto_typographic]
-  html_to_native: true
-  hard_wrap: false
-  syntax_highlighter: rouge
-  toc_levels: 2..3
-incremental: false
-permalink: pretty
-safe: false
-lsi: false
-exclude: ["_scripts", "tests", "apidocs/layouts", "Gemfile", "hooks", "index.html", "404.html"]
-
-# Component versions -- address like site.docker_ce_version
-# You can't have - characters in these for non-YAML reasons
-
-# TO USE ME:
-# jekyll serve --incremental --config _config_authoring.yml
-
-latest_engine_api_version: "1.40"
-docker_ce_version: "19.03"
-compose_version: "1.27.4"
-compose_file_v3: "3.8"
-compose_file_v2: "2.4"
-machine_version: "0.16.0"
-distribution_version: "2.7"
-
-collections:
-  samples:
-    output: true
-
-plugins:
-  - jekyll-redirect-from
-  - jekyll-relative-links
-  - jekyll-sitemap
-
-defaults:
-  - scope:
-      path: ""
-      type: "pages"
-    values:
-      layout: docs
-      toc_min: 2
-      toc_max: 3
-      tree: true
-
-  # Set the correct edit-URL for upstream resources. We usually don't create a direct
-  # edit link for these, and instead point to the directory that contains the file.
-  - scope:
-      path: engine/api/v1.*
-    values:
-      edit_url: "https://github.com/docker/docker/tree/master/docs/api"
-  - scope:
-      path: engine/deprecated
-    values:
-      edit_url: "https://github.com/docker/cli/tree/master/docs/"
-  - scope:
-      path: engine/extend
-    values:
-      edit_url: "https://github.com/docker/cli/tree/master/docs/extend"
-  - scope:
-      path: engine/reference
-    values:
-      edit_url: "https://github.com/docker/cli/tree/master/docs/reference"
-  - scope:
-      path: engine/reference/commandline
-    values:
-      edit_url: "https://github.com/docker/cli/tree/master/docs/reference/commandline"
-  - scope:
-      path: glossary
-    values:
-      edit_url: "https://github.com/docker/docker.github.io/blob/master/_data/glossary.yaml"
-  - scope:
-      path: notary/reference
-    values:
-      edit_url: "https://github.com/theupdateframework/notary/tree/master/docs/reference"
-  - scope:
-      path: registry/configuration
-    values:
-      edit_url: "https://github.com/docker/distribution/tree/master/docs"
-  - scope:
-      path: registry/spec
-    values:
-      edit_url: "https://github.com/docker/distribution/tree/master/docs/spec"
-  - scope:
-      path: compliance
-    values:
-      edit_url: "https://github.com/mirantis/compliance/tree/master/docs/compliance"
-
-  # Hide Enterprise content from sitemap. These directories still contains stubs
-  # that are needed to redirect old URLs
-  - scope:
-      path: "datacenter"
-    values:
-      sitemap: false
-      title: Docker Enterprise moved to Mirantis
-  - scope:
-      path: "desktop/enterprise"
-    values:
-      sitemap: false
-  - scope:
-      path: "ee"
-    values:
-      sitemap: false
-      title: Docker Enterprise moved to Mirantis
-  - scope:
-      path: "machine"
-    values:
-      sitemap: false
-  - scope:
-      path: "samples/library"
-    values:
-      sitemap: false
-
-# Assets
-#
-# We specify the directory for Jekyll so we can use @imports.
-sass:
-  sass_dir:          _scss
-  style:            :compressed

_config_production.yml

@@ -0,0 +1,11 @@
+
+# Include files that are excluded in "development" ("enterprise" stubs) for production
+exclude: ["_scripts", "404.html", "index.html"]
+
+# Google Analytics, etc.
+google_analytics: GTM-WL2QLG5
+polldaddy_id:     8453675
+
+# Assets
+sass:
+  style:    compressed

_includes/body.html

@@ -73,5 +73,5 @@
         {% include footer.html %}
     </footer>
     <script>const pageURL = "{{ page.url }}";</script>
-    {%- include analytics/polldaddy.html -%}
+    {%- if jekyll.environment == 'production' -%}{%- include analytics/polldaddy.html -%}{%- endif -%}
 </body>

_includes/head.html

@@ -24,16 +24,20 @@
         {%- assign page_description = content | strip_html | strip | truncatewords: 30 -%}
     {%- endif -%}
 {%- endif -%}
+{%- assign domain_name = 'https://docs.docker.com' -%}
+{%- if jekyll.environment == 'development' -%}
+{%- assign domain_name = 'https://localhost:4000' -%}
+{%- endif -%}
 <head>
   <meta http-equiv="Content-Type" content="text/html; charset=UTF-8">
   {%- if page.sitemap == false or site.GH_ENV == "gh_pages" %}
   <meta name="robots" content="noindex"/>
   {%- endif %}
-  {%- if site.google_analytics != '' -%}{%- include analytics/google_analytics.html GOOGLE_ID=site.google_analytics -%}{%- endif -%}
+  {%- if jekyll.environment == 'production' and site.google_analytics != '' -%}{%- include analytics/google_analytics.html GOOGLE_ID=site.google_analytics -%}{%- endif -%}
   <title>{{ page.title | default: page_title }} | Docker Documentation</title>
   <meta name="description" content="{{ page.description | default: page_description | escape}}" />
   <meta name="keywords" content="{{ page.keywords | default: 'docker, docker open source, docker platform, distributed applications, microservices, containers, docker containers, docker software, docker virtualization' }}">
-  <link rel="canonical" href="https://docs.docker.com{{ page.url }}" />
+  <link rel="canonical" href="{{ domain_name }}{{ page.url }}" />
 
   <!-- favicon -->
   <link rel="icon" type="image/x-icon" href="/favicons/docs@2x.ico" sizes="129x128">

docker-compose.yml

@@ -1,7 +1,21 @@
 version: "3.7"
 services:
   docs:
+    # By default, docker-compose up --build builds docs for a development
+    # environment (no Google Analytics, omitting some enterprise redirects,
+    # etc.
+    #
+    # To test a "production" build, override the environment using:
+    #
+    # JEKYLL_ENV=production docker-compose up --build
     build:
+      args:
+        # FIXME: docker-compose should behave the same as the docker CLI here
+        # and if `JEKYLL_ENV` is not set in the current environment, ignore
+        # the --build-arg, and use the default that's defined in the Dockerfile.
+        # Setting a default here as a workaround.
+        # - JEKYLL_ENV
+        - JEKYLL_ENV=${JEKYLL_ENV:-development}
       context: .
     image: docs/docstage
     ports: