Merge pull request #13410 from thaJeztah/go_get_started_touchups

guides: use include for "create a Dockerfile" sections

_includes/guides/create-dockerfile.md

@@ -0,0 +1,39 @@
+A Dockerfile is a text document that contains the instructions to assemble a
+Docker image. When we tell Docker to build our image by executing the `docker build`
+command, Docker reads these instructions, executes them, and creates a Docker
+image as a result.
+
+Let’s walk through the process of creating a Dockerfile for our application. In
+the root of your project, create a file named `Dockerfile` and open this file in
+your text editor.
+
+> **What to name your Dockerfile?**
+>
+> The default filename to use for a Dockerfile is `Dockerfile` (without a file-
+> extension). Using the default name allows you to run the `docker build` command
+> without having to specify additional command flags.
+>
+> Some projects may need distinct Dockerfiles for specific purposes. A common
+> convention is to name these `Dockerfile.<something>` or `<something>.Dockerfile`.
+> Such Dockerfiles can then be used through the `--file` (or `-f` shorthand)
+> option on the `docker build` command. Refer to the
+> ["Specify a Dockerfile" section](/engine/reference/commandline/build/#specify-a-dockerfile--f)
+> in the `docker build` reference to learn about the `--file` option.
+>
+> We recommend using the default (`Dockerfile`) for your project's primary
+> Dockerfile, which is what we'll use for most examples in this guide.
+
+The first line to add to a 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, and 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.

language/golang/build-images.md

@@ -115,17 +115,14 @@ Having established that the server is running and is accessible, let's proceed t
 
 ## Create a Dockerfile for the application
 
-A `Dockerfile` is a text document that contains the instructions for building a Docker image. When we tell Docker to build our image by executing the `docker build` command, Docker reads these instructions and executes them one by one and creates a Docker image as a result.
+{% include guides/create-dockerfile.md %}
 
-Let’s walk through the process of creating a `Dockerfile` for our application. In the root of your working directory, create a file named `Dockerfile` and open this file in your text editor.
+Next, we need to add a line in our Dockerfile that tells Docker what base image
-
+we would like to use for our application.
-> **Note**
->
-> The name of the file is not _that_ 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.
 
 ```dockerfile
+# syntax=docker/dockerfile:1
+
 FROM golang:1.16-alpine
 ```
 
@@ -191,6 +188,8 @@ CMD [ "/docker-gs-ping" ]
 Here's the complete `Dockerfile`:
 
 ```dockerfile
+# syntax=docker/dockerfile:1
+
 FROM golang:1.16-alpine
 
 WORKDIR /app
@@ -211,6 +210,8 @@ CMD [ "/docker-gs-ping" ]
 The `Dockerfile` may also contain _comments_. They always begin with a `#` symbol and make no difference to Docker. The comments are there for the convenience of humans tasked to maintain the `Dockerfile`:
 
 ```dockerfile
+# syntax=docker/dockerfile:1
+
 # Alpine is chosen for its small footprint
 # compared to Ubuntu
 FROM golang:1.16-alpine
@@ -335,10 +336,11 @@ The `Dockerfile.multistage` in the sample application's repo has the following c
 
 {% raw %}
 ```dockerfile
+# syntax=docker/dockerfile:1
+
 ##
 ## Build
 ##
-
 FROM golang:1.16-buster AS build
 
 WORKDIR /app
@@ -354,7 +356,6 @@ RUN go build -o /docker-gs-ping
 ##
 ## Deploy
 ##
-
 FROM gcr.io/distroless/base-debian10
 
 WORKDIR /

language/java/build-images.md

@@ -10,7 +10,7 @@ description: Learn how to build your first Docker image by writing a Dockerfile
 
 Work through the orientation and setup in Get started [Part 1](../../get-started/index.md){:target="_blank" rel="noopener" class="_"} to understand Docker concepts. Refer to the following section for Java prerequisites.
 
-{% include enable-buildkit.md %}
+{% include guides/enable-buildkit.md %}
 
 ## Overview
 
@@ -58,28 +58,7 @@ PetClinicApplication in 11.743 seconds (JVM running for 12.364)
 
 Now that our application is running properly, let’s take a look at creating a Dockerfile.
 
-A Dockerfile is a text document that contains all the commands a user could call on the command line to assemble an image. When we tell Docker to build our image by executing the `docker build` command, Docker reads these instructions and execute them sequentially and creates a Docker image.
+{% include guides/create-dockerfile.md %}
-
-Let’s walk through the steps on creating a Dockerfile for our application. In the root of your working directory, create a file named `Dockerfile` and open this file in your text editor.
-
-> **Note**
->
-> 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 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
-must appear before any other comment, whitespace, or Dockerfile instruction in
-your Dockerfile, and 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.

language/nodejs/build-images.md

@@ -12,7 +12,7 @@ redirect_from:
 
 Work through the orientation and setup in Get started [Part 1](../../get-started/index.md) to understand Docker concepts.
 
-{% include enable-buildkit.md %}
+{% include guides/enable-buildkit.md %}
 
 ## Overview
 
@@ -93,28 +93,7 @@ We will now continue to build and run the application in Docker.
 
 ## Create a Dockerfile for Node.js
 
-A Dockerfile is a text document that contains all the commands a user could call on the command line to assemble an image. When we tell Docker to build our image by executing the `docker build` command, Docker reads these instructions and executes them one by one and creates a Docker image as a result.
+{% include guides/create-dockerfile.md %}
-
-Let’s walk through the process of creating a Dockerfile for our application. In the root of your working directory, create a file named `Dockerfile` and open this file in your text editor.
-
-> **Note**
->
-> 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 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.

language/python/build-images.md

@@ -10,7 +10,7 @@ description: Learn how to build your first Docker image by writing a Dockerfile
 
 Work through the orientation and setup in Get started [Part 1](../../get-started/index.md) to understand Docker concepts.
 
-{% include enable-buildkit.md %}
+{% include guides/enable-buildkit.md %}
 
 ## Overview
 
@@ -64,28 +64,7 @@ Switch back to the terminal where our server is running and you should see the f
 
 Now that our application is running properly, let’s take a look at creating a Dockerfile.
 
-A Dockerfile is a text document that contains all the commands a user could call on the command line to assemble an image. When we tell Docker to build our image by executing the `docker build` command, Docker reads these instructions, executes them consecutively, and creates a Docker image as a result.
+{% include guides/create-dockerfile.md %}
-
-Let’s walk through creating a Dockerfile for our application. In the root of your working directory, create a file named `Dockerfile` and open this file in your text editor.
-
-> **Note**
->
-> 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 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.