Publish updates from master

.github/workflows/publish.yml

@@ -18,17 +18,20 @@ jobs:
           JEKYLL_ENV=development
           DOCS_AWS_REGION=us-east-1
           if [ "${{ github.ref }}" = "refs/heads/master" ]; then
+            DOCS_URL="https://docs-stage.docker.com"
             DOCS_S3_BUCKET="docs.docker.com-stage-us-east-1"
             DOCS_S3_CONFIG="_website-config-docs-stage.json"
             DOCS_LAMBDA_FUNCTION_CACHE="arn:aws:lambda:us-east-1:710015040892:function:docs-stage-cache-invalidator"
             DOCS_SLACK_MSG="Successfully promoted docs-stage from master. https://docs-stage.docker.com/"
           elif [ "${{ github.ref }}" = "refs/heads/published" ]; then
             JEKYLL_ENV=production
+            DOCS_URL="https://docs.docker.com"
             DOCS_S3_BUCKET="docs.docker.com-us-east-1"
             DOCS_S3_CONFIG="_website-config-docs.json"
             DOCS_LAMBDA_FUNCTION_CACHE="arn:aws:lambda:us-east-1:710015040892:function:docs-cache-invalidator"
             DOCS_SLACK_MSG="Successfully published docs. https://docs.docker.com/"
           elif [ "${{ github.ref }}" = "refs/heads/lab" ]; then
+            DOCS_URL="https://docs-lab.docker.com"
             DOCS_S3_BUCKET=""
             DOCS_LAMBDA_FUNCTION_CACHE=""
             DOCS_S3_CONFIG="_website-config-docs-lab.json"
@@ -37,6 +40,7 @@ jobs:
             exit 1
           fi
           echo "JEKYLL_ENV=$JEKYLL_ENV" >> $GITHUB_ENV
+          echo "DOCS_URL=$DOCS_URL" >> $GITHUB_ENV
           echo "DOCS_AWS_REGION=$DOCS_AWS_REGION" >> $GITHUB_ENV
           echo "DOCS_S3_BUCKET=$DOCS_S3_BUCKET" >> $GITHUB_ENV
           echo "DOCS_S3_CONFIG=$DOCS_S3_CONFIG" >> $GITHUB_ENV

.gitignore

@@ -5,6 +5,7 @@
 .jekyll-metadata
 _site/**
 .sass-cache/**
+.vscode
 CNAME
 _kbase/**
 /vendor

Dockerfile

@@ -10,7 +10,7 @@ ARG RUBY_VERSION=2.7.6
 ARG BUNDLER_VERSION=2.3.13
 
 ARG JEKYLL_ENV=development
-ARG DOMAIN=docs.docker.com
+ARG DOCS_URL=http://localhost:4000
 
 # Base stage for building
 FROM ruby:${RUBY_VERSION}-alpine AS base
@@ -44,28 +44,14 @@ COPY --from=vendored /out /
 # After building with jekyll, fix up some links
 FROM gem AS generate
 ARG JEKYLL_ENV
-ARG DOMAIN
+ARG DOCS_URL
 ENV TARGET=/out
 RUN --mount=type=bind,target=.,rw \
-  --mount=type=cache,target=/src/.jekyll-cache <<EOT
-set -eu
-if [ "${JEKYLL_ENV}" = "production" ]; then
-  (
-    set -x
-    bundle exec jekyll build --profile -d ${TARGET} --config _config.yml,_config_production.yml
-    sed -i "s#<loc>/#<loc>https://${DOMAIN}/#" "${TARGET}/sitemap.xml"
-  )
-else
-  (
-    set -x
-    bundle exec jekyll build --trace --profile -d ${TARGET}
-    mkdir -p ${TARGET}/js
-    echo '[]' > ${TARGET}/js/metadata.json
-  )
-fi
-find ${TARGET} -type f -name '*.html' | while read i; do
-  sed -i "s#\(<a[^>]* href=\"\)https://${DOMAIN}/#\1/#g" "$i"
-done
+    --mount=type=cache,target=/src/.jekyll-cache <<EOT
+  set -eu
+  CONFIG_FILES=_config.yml$([ "$JEKYLL_ENV" = "production" ] && echo ",_config_production.yml" || true)
+  set -x
+  bundle exec jekyll build --profile -d ${TARGET} --config ${CONFIG_FILES}
 EOT
 
 # htmlproofer checks for broken links

_config.yml

@@ -30,7 +30,6 @@ exclude:
   - datacenter
   - docker-bake.hcl
   - ee
-  - js/metadata.json
   - LICENSE
   - Makefile
   - README.md
@@ -67,12 +66,15 @@ compose_switch_version: "1.0.4"
 # which we show a badge (currently: API v1.40, or "Docker 19.03").
 min_api_threshold: 1.40
 
+# Enable search autocompletion (requires metadata.json to be generated)
+local_search: true
+
 # List of plugins to enable for local development builds. Mostly the same as
-# for production, but without the "jekyll-sitemap" plugin, which is not needed
-# for previewing, and excluding saves some time to build
+# for production.
 plugins:
   - jekyll-redirect-from
   - jekyll-relative-links
+  - jekyll-sitemap
 
 # Assets
 #
@@ -87,10 +89,7 @@ sass:
 # Set default options / metadata for some paths.
 #
 # Setting options here prevents having to repeat the same option in front-matter
-# on every page. Avoid using wildcards, such as "path: engine/api/v1.*", as
-# limitations in Jekyll cause those to introduce a _severe_ impact on build-time,
-# affecting generation of (e.g.) sitemap.xml and metadata.json, resulting in the
-# total build to take 60 seconds longer to build (!).
+# on every page.
 defaults:
   # Default one for development builds (local and PR previews)
   # sitemap is disabled here but not for production in _config_production.yml
@@ -99,7 +98,6 @@ defaults:
       type: "pages"
     values:
       layout: docs
-      sitemap: false
       toc_min: 2
       toc_max: 4
 
@@ -170,6 +168,9 @@ fetch-remote:
       - dest: "build/bake"
         src:
           - "docs/guides/bake/**"
+      - dest: "build/buildx/drivers"
+        src:
+          - "docs/guides/drivers/**"
 
   - repo: "https://github.com/distribution/distribution"
     default_branch: "main"

_config_production.yml

@@ -17,20 +17,12 @@ exclude:
 google_analytics: GTM-WL2QLG5
 polldaddy_id:     8453675
 
-# Enable search autocompletion (requires metadata.json to be generated)
-local_search: true
-
-plugins:
-  - jekyll-redirect-from
-  - jekyll-relative-links
-  - jekyll-sitemap
-
 # Assets
 #
 # For production/deploy, we build css with the "compressed" format, to produce
 # smaller files.
 sass:
-  style:    compressed
+  style: compressed
 
 collections:
   samples:
@@ -39,10 +31,7 @@ collections:
 # Set default options / metadata for some paths.
 #
 # Setting options here prevents having to repeat the same option in front-matter
-# on every page. Avoid using wildcards, such as "path: engine/api/v1.*", as
-# limitations in Jekyll cause those to introduce a _severe_ impact on build-time,
-# affecting generation of (e.g.) sitemap.xml and metadata.json, resulting in the
-# total build to take 60 seconds longer to build (!).
+# on every page.
 #
 # The list below is used for *production* deploys, and overrides the one defined
 # in "_config.yml", which is used for local builds and pull-request previews.

_data/toc.yaml

@@ -1199,6 +1199,8 @@ manuals:
           title: Explore networking features
         - path: /desktop/mac/permission-requirements/
           title: Docker Desktop permission requirements for Mac
+        - path: /desktop/windows/permission-requirements/
+          title: Docker Desktop permission requirements for Windows
         - path: /desktop/windows/wsl/
           title: Docker Desktop WSL 2 backend on Windows
         - path: /desktop/vm-vdi/
@@ -1400,6 +1402,16 @@ manuals:
           title: Buildx overview
         - path: /build/buildx/install/
           title: Install Buildx
+        - sectiontitle: Drivers
+          section:
+            - path: /build/buildx/drivers/
+              title: Overview
+            - path: /build/buildx/drivers/docker-container/
+              title: Docker container driver
+            - path: /build/buildx/drivers/kubernetes/
+              title: Kubernetes driver
+            - path: /build/buildx/drivers/remote/
+              title: Remote driver
         - path: /build/buildx/multiple-builders/
           title: Using multiple builders
         - path: /build/buildx/multiplatform-images/

_plugins/fix_swagger.rb

@@ -0,0 +1,25 @@
+require 'jekyll'
+require 'octopress-hooks'
+
+require_relative 'util.rb'
+
+module Jekyll
+  class FetchRemote < Octopress::Hooks::Site
+    def post_read(site)
+      beginning_time = Time.now
+      Jekyll.logger.info "Starting plugin fix_swagger.rb..."
+
+      files = Dir.glob(%w[./docker-hub/api/*.yaml ./engine/api/*.yaml])
+      Jekyll.logger.info "  Fixing up #{files.size} swagger file(s)..."
+      files.each do |f|
+        Jekyll.logger.info "    #{f}"
+        text = File.read(f)
+        replace = text.gsub(get_docs_url, "")
+        File.open(f, "w") { |f2| f2.puts replace }
+      end
+
+      end_time = Time.now
+      Jekyll.logger.info "done in #{(end_time - beginning_time)} seconds"
+    end
+  end
+end

_plugins/fix_url.rb

@@ -0,0 +1,29 @@
+require 'jekyll'
+require 'octopress-hooks'
+
+require_relative 'util.rb'
+
+module Jekyll
+  class FetchRemote < Octopress::Hooks::Site
+    def post_write(site)
+      beginning_time = Time.now
+      Jekyll.logger.info "Starting plugin fix_url.rb..."
+
+      # TODO: use dynamic URL from util.get_docs_url instead of hardcoded one
+      #   but needs to remove first all absolute URLs in our code base.
+      docs_url = "https://docs.docker.com"
+
+      dest = site.config['destination'] || '_site'
+      files = Dir.glob("#{dest}/**/*.html")
+      Jekyll.logger.info "  Fixing up URLs in #{files.size} html file(s) to be relative"
+      files.each do|f|
+        text = File.read(f)
+        replace = text.gsub(/(<a[^>]* href=\")#{docs_url}/, '\1')
+        File.open(f, "w") { |f2| f2.puts replace }
+      end
+
+      end_time = Time.now
+      Jekyll.logger.info "done in #{(end_time - beginning_time)} seconds"
+    end
+  end
+end

_plugins/update_sitemap.rb

@@ -0,0 +1,18 @@
+require_relative 'util.rb'
+
+Jekyll::Hooks.register :site, :post_write do |site|
+  beginning_time = Time.now
+  Jekyll.logger.info "Starting plugin update_sitemap.rb..."
+
+  sitemap_path = File.join(site.dest, 'sitemap.xml')
+
+  if File.exist?(sitemap_path)
+    sitemap_file = File.read(sitemap_path)
+    replace = sitemap_file.gsub!("<loc>/", "<loc>#{get_docs_url}/")
+    Jekyll.logger.info "  Replacing '<loc>/' with '<loc>#{get_docs_url}/' in #{sitemap_path}"
+    File.open(sitemap_path, "w") { |file| file.puts replace }
+  end
+
+  end_time = Time.now
+  Jekyll.logger.info "done in #{(end_time - beginning_time)} seconds"
+end

_plugins/util.rb

@@ -0,0 +1,5 @@
+def get_docs_url
+  # DEPLOY_URL is from Netlify for preview
+  # https://docs.netlify.com/configure-builds/environment-variables/#deploy-urls-and-metadata
+  ENV['DEPLOY_URL'] || ENV['DOCS_URL'] || 'https://docs.docker.com'
+end

build/buildx/drivers/docker-container.md

@@ -0,0 +1,7 @@
+---
+title: "Docker container driver"
+keywords: build, buildx, driver, builder, docker-container
+fetch_remote:
+  line_start: 2
+  line_end: -1
+---

build/buildx/drivers/index.md

@@ -0,0 +1,7 @@
+---
+title: "Buildx drivers overview"
+keywords: build, buildx, driver, builder, docker-container, kubernetes, remote
+fetch_remote:
+  line_start: 2
+  line_end: -1
+---

build/buildx/drivers/kubernetes.md

@@ -0,0 +1,7 @@
+---
+title: "Kubernetes driver"
+keywords: build, buildx, driver, builder, kubernetes
+fetch_remote:
+  line_start: 2
+  line_end: -1
+---

build/buildx/drivers/remote.md

@@ -0,0 +1,22 @@
+---
+title: "Remote driver"
+keywords: build, buildx, driver, builder, remote
+fetch_remote:
+  line_start: 2
+  line_end: -1
+---
+
+> Beta
+>
+> Remote driver is currently available as a beta feature. We recommend that you
+> do not use this feature in production environments. You can [build Buildx from source](https://github.com/docker/buildx#building){: target="_blank" rel="noopener" class="_"}
+> to test the remote driver or use the following command to download and
+> install an edge release of Buildx:
+> 
+> ```console
+> $ echo "FROM docker/buildx-bin:master" | docker buildx build --platform=local --output . -f - .
+> $ mkdir -p ~/.docker/cli-plugins/
+> $ mv buildx ~/.docker/cli-plugins/docker-buildx
+> ```
+{: .important}
+

build/buildx/index.md

@@ -34,19 +34,18 @@ In addition, Buildx also supports new features that are not yet available for
 regular `docker build` like building manifest lists, distributed caching, and
 exporting build results to OCI image tarballs.
 
-You can run Buildx in different configurations that are exposed through a driver
-concept. Currently, Docker supports a "docker" driver that uses the BuildKit
-library bundled into the Docker daemon binary, and a "docker-container" driver
-that automatically launches BuildKit inside a Docker container.
-
-The user experience of using Buildx is very similar across drivers. However,
-there are some features that are not currently supported by the "docker" driver,
-because the BuildKit library which is bundled into docker daemon uses a different
-storage component. In contrast, all images built with the "docker" driver are
-automatically added to the "docker images" view by default, whereas when using
-other drivers, the method for outputting an image needs to be selected
-with `--output`.
+Buildx is flexible and can be run in different configurations that are exposed
+through various "drivers". Each driver defines how and where a build should
+run, and have different feature sets.
 
+We currently support the following drivers:
+
+* The `docker` driver ([reference](/engine/reference/commandline/buildx_create/#driver))
+* The `docker-container` driver ([guide](drivers/docker-container.md), [reference](/engine/reference/commandline/buildx_create/#driver))
+* The `kubernetes` driver ([guide](drivers/kubernetes.md), [reference](/engine/reference/commandline/buildx_create/#driver))
+* The `remote` driver ([guide](drivers/remote.md))
+
+For more information on drivers, see the [drivers guide](drivers/index.md).
 
 ## High-level build options with Bake
 

build/buildx/install.md

@@ -75,4 +75,4 @@ sets up docker builder command as an alias to `docker buildx`. This results in
 the ability to have [`docker build`](../../engine/reference/commandline/build.md)
 use the current buildx builder.
 
-To remove this alias, run [`docker buildx uninstall`](../../engine/reference/commandline/buildx_uninstall.md).
+To remove this alias, run [`docker buildx uninstall`](../../engine/reference/commandline/buildx_uninstall.md).