Merge pull request #12703 from thaJeztah/dockerfile_syntax

use Dockerfile "syntax" directive in examples

buildx/working-with-buildx.md

@@ -148,6 +148,7 @@ inside your Dockerfile and can be leveraged by the processes running as part
 of your build.
 
 ```dockerfile
+# syntax=docker/dockerfile:1
 FROM --platform=$BUILDPLATFORM golang:alpine AS build
 ARG TARGETPLATFORM
 ARG BUILDPLATFORM

compose/compose-file/compose-file-v2.md

@@ -182,6 +182,8 @@ build process.
 First, specify the arguments in your Dockerfile:
 
 ```dockerfile
+# syntax=docker/dockerfile:1
+
 ARG buildno
 ARG gitcommithash
 

compose/compose-file/compose-file-v3.md

@@ -247,6 +247,8 @@ build process.
 First, specify the arguments in your Dockerfile:
 
 ```dockerfile
+# syntax=docker/dockerfile:1
+
 ARG buildno
 ARG gitcommithash
 

compose/gettingstarted.md

@@ -85,6 +85,7 @@ In your project directory, create a file named `Dockerfile` and paste the
 following:
 
 ```dockerfile
+# syntax=docker/dockerfile:1
 FROM python:3.7-alpine
 WORKDIR /code
 ENV FLASK_APP=app.py

config/containers/multi-service_container.md

@@ -76,6 +76,7 @@ this in a few different ways.
   Next, the Dockerfile:
 
   ```dockerfile
+  # syntax=docker/dockerfile:1
   FROM ubuntu:latest
   COPY my_first_process my_first_process
   COPY my_second_process my_second_process
@@ -110,6 +111,7 @@ this in a few different ways.
   ```
 
   ```dockerfile
+  # syntax=docker/dockerfile:1
   FROM ubuntu:latest
   COPY my_main_process my_main_process
   COPY my_helper_process my_helper_process
@@ -127,6 +129,7 @@ this in a few different ways.
   Dockerfile.
 
   ```dockerfile
+  # syntax=docker/dockerfile:1
   FROM ubuntu:latest
   RUN apt-get update && apt-get install -y supervisor
   RUN mkdir -p /var/log/supervisor

desktop/dashboard.md

@@ -49,7 +49,7 @@ Let's start a sample application. Download the [Example voting app](https://gith
 
 To start the application, navigate to the directory containing the example voting application in the CLI and run `docker-compose up --build`.
 
-```shell
+```console
 $ docker-compose up --build
 Creating network "example-voting-app-master_front-tier" with the default driver
 Creating network "example-voting-app-master_back-tier" with the default driver

develop/develop-images/baseimages.md

@@ -62,6 +62,7 @@ in your `Dockerfile`. For example, to create a minimal container using
 `scratch`:
 
 ```dockerfile
+# syntax=docker/dockerfile:1
 FROM scratch
 ADD hello /
 CMD ["/hello"]

develop/develop-images/build_enhancements.md

@@ -19,7 +19,8 @@ on performance, storage management, feature functionality, and security.
   information for building new images with a specified Dockerfile 
 
 For more information on build options, see the reference guide on the
-[command line build options](/engine/reference/commandline/build/).
+[command line build options](../../engine/reference/commandline/build.md) and
+the [Dockerfile reference](/engine/reference/builder/) page.
 
 
 ## Requirements
@@ -115,9 +116,16 @@ frontend. To override the default frontend, set the first line of the
 `Dockerfile` as a comment with a specific frontend image: 
 
 ```dockerfile
-# syntax = <frontend image>, e.g. # syntax = docker/dockerfile:1.0-experimental
+# syntax=<frontend image>, e.g. # syntax=docker/dockerfile:1
 ```
 
+The examples on this page use features that are available in `docker/dockerfile`
+version 1.2.0 and up. We recommend using `docker/dockerfile:1`, which always
+points to the latest release of the version 1 syntax. BuildKit automatically
+checks for updates of the syntax before building, making sure you are using the
+most current version. Learn more about the `syntax` directive in the
+[Dockerfile reference](/engine/reference/builder/#syntax).
+
 ## New Docker Build secret information
 
 The new `--secret` flag for docker build allows the user to pass secret
@@ -138,13 +146,11 @@ For example, with a secret piece of information stored in a text file:
 $ echo 'WARMACHINEROX' > mysecret.txt
 ```
 
-And with a Dockerfile that specifies use of a BuildKit frontend
-`docker/dockerfile:1.0-experimental`, the secret can be accessed. 
-
-For example:
+Within a Dockerfile that uses BuildKit frontend `docker/dockerfile:1.2` or up,
+the secret can be accessed using the `--mount` option:
 
 ```dockerfile
-# syntax = docker/dockerfile:1.0-experimental
+# syntax=docker/dockerfile:1
 FROM alpine
 
 # shows secret from default secret location:
@@ -202,7 +208,7 @@ make programs relying on SSH automatically use that socket.
 Here is an example Dockerfile using SSH in the container:
 
 ```dockerfile
-# syntax=docker/dockerfile:experimental
+# syntax=docker/dockerfile:1
 FROM alpine
 
 # Install ssh client and git

develop/develop-images/dockerfile_best-practices.md

@@ -23,6 +23,7 @@ Dockerfile  instruction. The layers are stacked and each one is a delta of the
 changes from the previous layer. Consider this `Dockerfile`:
 
 ```dockerfile
+# syntax=docker/dockerfile:1
 FROM ubuntu:18.04
 COPY . /app
 RUN make /app
@@ -271,7 +272,8 @@ frequently changed:
 A Dockerfile for a Go application could look like:
 
 ```dockerfile
-FROM golang:1.11-alpine AS build
+# syntax=docker/dockerfile:1
+FROM golang:1.16-alpine AS build
 
 # Install tools required for project
 # Run `docker build --no-cache .` to update dependencies
@@ -485,6 +487,7 @@ subsequent `apt-get install` instructions fail. For example, say you have a
 Dockerfile:
 
 ```dockerfile
+# syntax=docker/dockerfile:1
 FROM ubuntu:18.04
 RUN apt-get update
 RUN apt-get install -y curl
@@ -494,6 +497,7 @@ After building the image, all layers are in the Docker cache. Suppose you later
 modify `apt-get install` by adding extra package:
 
 ```dockerfile
+# syntax=docker/dockerfile:1
 FROM ubuntu:18.04
 RUN apt-get update
 RUN apt-get install -y curl nginx
@@ -653,6 +657,7 @@ still persists in this layer and its value can be dumped. You can test this by
 creating a Dockerfile like the following, and then building it.
 
 ```dockerfile
+# syntax=docker/dockerfile:1
 FROM alpine
 ENV ADMIN_USER="mark"
 RUN echo $ADMIN_USER > ./mark
@@ -674,6 +679,7 @@ improves readability. You could also put all of the commands into a shell script
 and have the `RUN` command just run that shell script.
 
 ```dockerfile
+# syntax=docker/dockerfile:1
 FROM alpine
 RUN export ADMIN_USER="mark" \
     && echo $ADMIN_USER > ./mark \

develop/develop-images/multistage-build.md

@@ -37,7 +37,8 @@ builder pattern above:
 **`Dockerfile.build`**:
 
 ```dockerfile
-FROM golang:1.7.3
+# syntax=docker/dockerfile:1
+FROM golang:1.16
 WORKDIR /go/src/github.com/alexellis/href-counter/
 COPY app.go .
 RUN go get -d -v golang.org/x/net/html \
@@ -52,6 +53,7 @@ and forget to continue the line using the `\` character, for example.
 **`Dockerfile`**:
 
 ```dockerfile
+# syntax=docker/dockerfile:1
 FROM alpine:latest  
 RUN apk --no-cache add ca-certificates
 WORKDIR /root/
@@ -97,7 +99,8 @@ multi-stage builds.
 **`Dockerfile`**:
 
 ```dockerfile
-FROM golang:1.7.3
+# syntax=docker/dockerfile:1
+FROM golang:1.16
 WORKDIR /go/src/github.com/alexellis/href-counter/
 RUN go get -d -v golang.org/x/net/html  
 COPY app.go .
@@ -136,7 +139,8 @@ the `COPY` instruction. This means that even if the instructions in your
 Dockerfile are re-ordered later, the `COPY` doesn't break.
 
 ```dockerfile
-FROM golang:1.7.3 AS builder
+# syntax=docker/dockerfile:1
+FROM golang:1.16 AS builder
 WORKDIR /go/src/github.com/alexellis/href-counter/
 RUN go get -d -v golang.org/x/net/html  
 COPY app.go    .
@@ -185,14 +189,15 @@ COPY --from=nginx:latest /etc/nginx/nginx.conf /nginx.conf
 You can pick up where a previous stage left off by referring to it when using the `FROM` directive. For example:
 
 ```dockerfile
-FROM alpine:latest as builder
+# syntax=docker/dockerfile:1
+FROM alpine:latest AS builder
 RUN apk --no-cache add build-base
 
-FROM builder as build1
+FROM builder AS build1
 COPY source1.cpp source.cpp
 RUN g++ -o /binary source.cpp
 
-FROM builder as build2
+FROM builder AS build2
 COPY source2.cpp source.cpp
 RUN g++ -o /binary source.cpp
 ```

engine/security/trust/trust_automation.md

@@ -75,6 +75,7 @@ you should set the environment variable `DOCKER_CONTENT_TRUST` either manually o
 in a scripted fashion. Consider the simple Dockerfile below.
 
 ```dockerfile
+# syntax=docker/dockerfile:1
 FROM docker/trusttest:latest
 RUN echo
 ```

engine/swarm/stack-deploy.md

@@ -105,6 +105,7 @@ counter whenever you visit it.
 4.  Create a file called `Dockerfile` and paste this in:
 
     ```dockerfile
+    # syntax=docker/dockerfile:1
     FROM python:3.4-alpine
     ADD . /code
     WORKDIR /code

get-started/02_our_app.md

@@ -43,6 +43,7 @@ see a few flaws in the Dockerfile below. But, don't worry! We'll go over them.
 1. Create a file named `Dockerfile` in the same folder as the file `package.json` with the following contents.
 
     ```dockerfile
+    # syntax=docker/dockerfile:1
     FROM node:12-alpine
     RUN apk add --no-cache python g++ make
     WORKDIR /app

get-started/09_image_best.md

@@ -100,6 +100,7 @@ times for your container images.
 Let's look at the Dockerfile we were using one more time...
 
 ```dockerfile
+# syntax=docker/dockerfile:1
 FROM node:12-alpine
 WORKDIR /app
 COPY . .
@@ -119,6 +120,7 @@ a change to the `package.json`. Make sense?
 1. Update the Dockerfile to copy in the `package.json` first, install dependencies, and then copy everything else in.
 
     ```dockerfile
+    # syntax=docker/dockerfile:1
     FROM node:12-alpine
     WORKDIR /app
     COPY package.json yarn.lock ./
@@ -229,6 +231,7 @@ that JDK isn't needed in production. Also, you might be using tools like Maven o
 Those also aren't needed in our final image. Multi-stage builds help.
 
 ```dockerfile
+# syntax=docker/dockerfile:1
 FROM maven AS build
 WORKDIR /app
 COPY . .
@@ -249,6 +252,7 @@ and more into static HTML, JS, and CSS. If we aren't doing server-side rendering
 for our production build. Why not ship the static resources in a static nginx container?
 
 ```dockerfile
+# syntax=docker/dockerfile:1
 FROM node:12 AS build
 WORKDIR /app
 COPY package* yarn.lock ./

get-started/nodejs/build-images.md

@@ -87,9 +87,27 @@ Let’s walk through the process of creating a Dockerfile for our application. I
 >
 > The name of the Dockerfile is not important but the default filename for many commands is simply `Dockerfile`. So, we’ll use that as our filename throughout this series.
 
-The first thing we need to do is to add a line in our Dockerfile that tells Docker what base image we would like to use for our application.
+The first line to add to the Dockerfile is a [`# syntax` parser directive](/engine/reference/builder/#syntax).
+While _optional_, this directive instructs the Docker builder what syntax to use
+when parsing the Dockerfile, and allows older Docker versions with BuildKit enabled
+to upgrade the parser before starting the build. [Parser directives](/engine/reference/builder/#parser-directives)
+must appear before any other comment, whitespace, or Dockerfile instruction in
+your Dockerfile, should be the first line in Dockerfiles.
 
 ```dockerfile
+# syntax=docker/dockerfile:1
+```
+
+We recommend using `docker/dockerfile:1`, which always points to the latest release
+of the version 1 syntax. BuildKit automatically checks for updates of the syntax
+before building, making sure you are using the most current version.
+
+Next, we need to add a line in our Dockerfile that tells Docker what base image
+we would like to use for our application.
+
+```dockerfile
+# syntax=docker/dockerfile:1
+
 FROM node:12.18.1
 ```
 
@@ -146,6 +164,8 @@ CMD [ "node", "server.js" ]
 Here's the complete Dockerfile.
 
 ```dockerfile
+# syntax=docker/dockerfile:1
+
 FROM node:12.18.1
 ENV NODE_ENV=production
 

language/nodejs/build-images.md

@@ -87,9 +87,27 @@ Let’s walk through the process of creating a Dockerfile for our application. I
 >
 > The name of the Dockerfile is not important but the default filename for many commands is simply `Dockerfile`. So, we’ll use that as our filename throughout this series.
 
-The first thing we need to do is to add a line in our Dockerfile that tells Docker what base image we would like to use for our application.
+The first line to add to the Dockerfile is a [`# syntax` parser directive](/engine/reference/builder/#syntax).
+While _optional_, this directive instructs the Docker builder what syntax to use
+when parsing the Dockerfile, and allows older Docker versions with BuildKit enabled
+to upgrade the parser before starting the build. [Parser directives](/engine/reference/builder/#parser-directives)
+must appear before any other comment, whitespace, or Dockerfile instruction in
+your Dockerfile, should be the first line in Dockerfiles.
 
 ```dockerfile
+# syntax=docker/dockerfile:1
+```
+
+We recommend using `docker/dockerfile:1`, which always points to the latest release
+of the version 1 syntax. BuildKit automatically checks for updates of the syntax
+before building, making sure you are using the most current version.
+
+Next, we need to add a line in our Dockerfile that tells Docker what base image
+we would like to use for our application.
+
+```dockerfile
+# syntax=docker/dockerfile:1
+
 FROM node:12.18.1
 ```
 
@@ -146,6 +164,8 @@ CMD [ "node", "server.js" ]
 Here's the complete Dockerfile.
 
 ```dockerfile
+# syntax=docker/dockerfile:1
+
 FROM node:12.18.1
 ENV NODE_ENV=production
 

language/nodejs/run-tests.md

@@ -110,6 +110,7 @@ Creating node-docker_notes_run ...
 In addition to running the tests on command, we can run them when we build our image, using a multi-stage Dockerfile. The following Dockerfile will run our tests and build our production image.
 
 ```dockerfile
+# syntax=docker/dockerfile:1
 FROM node:14.15.4 as base
 
 WORKDIR /code
@@ -166,6 +167,7 @@ This is great but at the moment we have to run two docker commands to build and
 Update your Dockerfile with the highlighted line below.
 
 ```dockerfile
+# syntax=docker/dockerfile:1
 FROM node:14.15.4 as base
 
 WORKDIR /code
@@ -186,8 +188,8 @@ CMD [ "node", "server.js" ]
 
 Now to run our tests, we just need to run the docker build command as above.
 
-```dockerfile
-docker build -t node-docker --target test .
+```console
+$ docker build -t node-docker --target test .
 Sending build context to Docker daemon  22.35MB
 Step 1/8 : FROM node:14.15.4 as base
  ---> f5be1883c8e0
@@ -235,8 +237,8 @@ Open the test/test.js fiole and change line 5 as follows.
 
 Now, run the same docker build command from above and observe that the build fails and the failing testing information is printed to the console.
 
-```shell
-docker build -t node-docker --target test .
+```console
+$ docker build -t node-docker --target test .
 Sending build context to Docker daemon  22.35MB
 Step 1/8 : FROM node:14.15.4 as base
  ---> 995ff80c793e

language/python/build-images.md

@@ -70,9 +70,27 @@ Let’s walk through creating a Dockerfile for our application. In the root of y
 >
 > The name of the Dockerfile is not important but the default filename for many commands is simply `Dockerfile`. Therefore, we’ll use that as our filename throughout this series.
 
-The first thing we need to do is to add a line in our Dockerfile that tells Docker what base image we would like to use for our application.
+The first line to add to the Dockerfile is a [`# syntax` parser directive](/engine/reference/builder/#syntax).
+While _optional_, this directive instructs the Docker builder what syntax to use
+when parsing the Dockerfile, and allows older Docker versions with BuildKit enabled
+to upgrade the parser before starting the build. [Parser directives](/engine/reference/builder/#parser-directives)
+must appear before any other comment, whitespace, or Dockerfile instruction in
+your Dockerfile, should be the first line in Dockerfiles.
 
 ```dockerfile
+# syntax=docker/dockerfile:1
+```
+
+We recommend using `docker/dockerfile:1`, which always points to the latest release
+of the version 1 syntax. BuildKit automatically checks for updates of the syntax
+before building, making sure you are using the most current version.
+
+Next, we need to add a line in our Dockerfile that tells Docker what base image
+we would like to use for our application.
+
+```dockerfile
+# syntax=docker/dockerfile:1
+
 FROM python:3.8-slim-buster
 ```
 
@@ -117,6 +135,8 @@ CMD [ "python3", "-m" , "flask", "run", "--host=0.0.0.0"]
 Here's the complete Dockerfile.
 
 ```dockerfile
+# syntax=docker/dockerfile:1
+
 FROM python:3.8-slim-buster
 
 WORKDIR /app

samples/apt-cacher-ng.md

@@ -19,7 +19,8 @@ the second download of any package almost instant.
 Use the following Dockerfile:
 
 ```dockerfile
-#
+# syntax=docker/dockerfile:1
+
 # Build: docker build -t apt-cacher .
 # Run: docker run -d -p 3142:3142 --name apt-cacher-run apt-cacher
 #
@@ -74,6 +75,7 @@ container.
 a local version of a common base:
 
 ```dockerfile
+# syntax=docker/dockerfile:1
 FROM ubuntu
 RUN echo 'Acquire::http { Proxy "http://dockerhost:3142"; };' >> /etc/apt/apt.conf.d/01proxy
 RUN apt-get update && apt-get install -y vim git

samples/aspnet-mssql-compose.md

@@ -45,6 +45,7 @@ configure this app to use our SQL Server database, and then create a
 1.  Create a `Dockerfile` within your app directory and add the following content:
 
     ```dockerfile
+    # syntax=docker/dockerfile:1
     FROM microsoft/dotnet:2.1-sdk
     COPY . /app
     WORKDIR /app

samples/django.md

@@ -28,6 +28,7 @@ and a `docker-compose.yml` file. (You can use either a `.yml` or `.yaml` extensi
 3. Add the following content to the `Dockerfile`.
 
    ```dockerfile
+   # syntax=docker/dockerfile:1
    FROM python:3
    ENV PYTHONUNBUFFERED=1
    WORKDIR /code

samples/dotnetcore.md

@@ -46,6 +46,7 @@ clone our [ASP.NET Docker Sample](https://github.com/dotnet/dotnet-docker/tree/m
    the `Dockerfile` to use the DLL file of your project.
 
 ```dockerfile
+# syntax=docker/dockerfile:1
 FROM mcr.microsoft.com/dotnet/sdk:5.0 AS build-env
 WORKDIR /app
 
@@ -88,6 +89,7 @@ obj/
     This method is preferred for CI tools like Jenkins, Azure DevOps, GitLab CI, etc. as you can use the same artifacts in multiple deployment models if Docker     isn't the only deployment model being used. Additionally, you'll be able to run unit tests and publish code coverage reports, or use custom plugins on the     artifacts built by the CI.
 
       ```dockerfile
+      # syntax=docker/dockerfile:1
       FROM mcr.microsoft.com/dotnet/aspnet:5.0
       COPY bin/Release/netcoreapp3.1/publish/ App/
       WORKDIR /App

samples/postgresql_service.md

@@ -19,10 +19,7 @@ PostgreSQL documentation to fine-tune these settings so that it is
 suitably secure.
 
 ```dockerfile
-#
-# example Dockerfile for https://docs.docker.com/engine/examples/postgresql_service/
-#
-
+# syntax=docker/dockerfile:1
 FROM ubuntu:16.04
 
 # Add the PostgreSQL PGP key to verify their Debian packages.

samples/rails.md

@@ -17,6 +17,7 @@ Docker container containing its dependencies. Defining dependencies is done usin
 a file called `Dockerfile`. To begin with, the  Dockerfile consists of:
 
 ```dockerfile
+# syntax=docker/dockerfile:1
 FROM ruby:2.5
 RUN apt-get update -qq && apt-get install -y nodejs postgresql-client
 WORKDIR /myapp

samples/running_riak_service.md

@@ -22,6 +22,7 @@ of. We use [Ubuntu](https://hub.docker.com/_/ubuntu/) (tag:
 `trusty`), which is available on [Docker Hub](https://hub.docker.com):
 
 ```dockerfile
+# syntax=docker/dockerfile:1
 # Riak
 #
 # VERSION       0.1.1

storage/storagedriver/index.md

@@ -30,6 +30,7 @@ instruction in the image's Dockerfile. Each layer except the very last one is
 read-only. Consider the following Dockerfile:
 
 ```dockerfile
+# syntax=docker/dockerfile:1
 FROM ubuntu:18.04
 COPY . /app
 RUN make /app
@@ -164,6 +165,7 @@ Now imagine that you have two different Dockerfiles. You use the first one to
 create an image called `acme/my-base-image:1.0`.
 
 ```dockerfile
+# syntax=docker/dockerfile:1
 FROM ubuntu:18.04
 COPY . /app
 ```
@@ -172,6 +174,7 @@ The second one is based on `acme/my-base-image:1.0`, but has some additional
 layers:
 
 ```dockerfile
+# syntax=docker/dockerfile:1
 FROM acme/my-base-image:1.0
 CMD /app/hello.sh
 ```
@@ -210,7 +213,7 @@ layers are the same.
     include the final `.` in the command. That sets the `PATH`, which tells
     Docker where to look for any files that need to be added to the image.
 
-    ```bash
+    ```console
     $ docker build -t acme/my-base-image:1.0 -f Dockerfile.base .
     Sending build context to Docker daemon  812.4MB
     Step 1/2 : FROM ubuntu:18.04
@@ -224,7 +227,7 @@ layers are the same.
 
 6.  Build the second image.
 
-    ```bash
+    ```console
     $ docker build -t acme/my-final-image:1.0 -f Dockerfile .
 
     Sending build context to Docker daemon  4.096kB
@@ -240,7 +243,7 @@ layers are the same.
 
 7.  Check out the sizes of the images:
 
-    ```bash
+    ```console
     $ docker image ls
 
     REPOSITORY                         TAG                     IMAGE ID            CREATED             SIZE
@@ -250,7 +253,7 @@ layers are the same.
 
 8.  Check out the layers that comprise each image:
 
-    ```bash
+    ```console
     $ docker history bd09118bcef6
     IMAGE               CREATED             CREATED BY                                      SIZE                COMMENT
     bd09118bcef6        4 minutes ago       /bin/sh -c #(nop) COPY dir:35a7eb158c1504e...   100B                
@@ -262,7 +265,7 @@ layers are the same.
     <missing>           3 months ago        /bin/sh -c #(nop) ADD file:eef57983bd66e3a...   103MB      
     ```
 
-    ```bash
+    ```console
     $ docker history dbf995fc07ff
 
     IMAGE               CREATED             CREATED BY                                      SIZE                COMMENT

test.md

@@ -779,7 +779,9 @@ command=/usr/sbin/sshd -D
 To enable syntax highlighting for Dockerfiles, use the `conf` lexer, for now.
 In the future, native Dockerfile support is coming to Rouge.
 
-```conf
+```dockerfile
+# syntax=docker/dockerfile:1
+
 #
 # example Dockerfile for https://docs.docker.com/examples/postgresql_service/
 #