diff --git a/_includes/guides/create-dockerfile.md b/_includes/guides/create-dockerfile.md new file mode 100644 index 0000000000..ecc616bd86 --- /dev/null +++ b/_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.` or `.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. \ No newline at end of file diff --git a/_includes/enable-buildkit.md b/_includes/guides/enable-buildkit.md similarity index 100% rename from _includes/enable-buildkit.md rename to _includes/guides/enable-buildkit.md diff --git a/language/golang/build-images.md b/language/golang/build-images.md index 8a15eaa38f..beea14372a 100644 --- a/language/golang/build-images.md +++ b/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. - -> **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. +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 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 / diff --git a/language/java/build-images.md b/language/java/build-images.md index c4b9bd0e70..ab3f0a9ea3 100644 --- a/language/java/build-images.md +++ b/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. - -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. +{% include guides/create-dockerfile.md %} Next, we need to add a line in our Dockerfile that tells Docker what base image we would like to use for our application. diff --git a/language/nodejs/build-images.md b/language/nodejs/build-images.md index 8957892e68..8c0a520aad 100644 --- a/language/nodejs/build-images.md +++ b/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. - -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. +{% include guides/create-dockerfile.md %} Next, we need to add a line in our Dockerfile that tells Docker what base image we would like to use for our application. diff --git a/language/python/build-images.md b/language/python/build-images.md index d862129ee5..f2012a2a66 100644 --- a/language/python/build-images.md +++ b/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. - -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. +{% include guides/create-dockerfile.md %} Next, we need to add a line in our Dockerfile that tells Docker what base image we would like to use for our application.