diff --git a/_includes/guides/create-dockerfile.md b/_includes/guides/create-dockerfile.md deleted file mode 100644 index ecc616bd8614..000000000000 --- a/_includes/guides/create-dockerfile.md +++ /dev/null @@ -1,39 +0,0 @@ -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/build/building/packaging.md b/build/building/packaging.md index 6205b023b5c9..0ea1a1a47579 100644 --- a/build/building/packaging.md +++ b/build/building/packaging.md @@ -29,6 +29,21 @@ multi-layer image builds based on your unique configurations. Dockerfiles can start simple and grow with your needs and support images that require complex instructions. For all the possible instructions, see the [Dockerfile reference](../../engine/reference/builder.md). +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`. 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.md#specify-a-dockerfile--f) +in the `docker build` reference to learn about the `--file` option. + +> **Note** +> +> We recommend using the default (`Dockerfile`) for your project's primary +> Dockerfile. + Docker images consist of **read-only layers**, each resulting from an instruction in the Dockerfile. Layers are stacked sequentially and each one is a delta representing the changes applied to the previous layer. @@ -80,16 +95,23 @@ EXPOSE 8000 CMD flask run --host 0.0.0.0 --port 8000 ``` -We start by specifying the [syntax directive](../../engine/reference/builder.md#syntax). -It pins the exact version of the Dockerfile syntax we're using: +The first line to add to a Dockerfile is a [`# syntax` parser directive](../../engine/reference/builder.md#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](../buildkit/index.md#getting-started) +to use a specific [Dockerfile frontend](../buildkit/dockerfile-frontend.md) +before starting the build. [Parser directives](../../engine/reference/builder.md/#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 ``` -As a [best practice](../../develop/dev-best-practices.md), this should be the -very first line in all our Dockerfiles as it informs BuildKit the right version -of the Dockerfile to use. +> **Note** +> +> 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 define the first instruction: @@ -185,11 +207,18 @@ To test our Dockerfile, we'll first build it using the [`docker build` command]( $ docker build -t test:latest . ``` -* `-t test:latest` option specifies the name (required) and tag (optional) of - the image we're building. -* `.` specifies the build context as the current directory. In this example, - this is where build expects to find the Dockerfile and the local files the - Dockerfile needs to access, in this case your python application. +Here `-t test:latest` option specifies the name (required) and tag (optional) +of the image we're building. `.` specifies the build context as the current +directory. In this example, this is where build expects to find the Dockerfile +and the local files the Dockerfile needs to access, in this case your Python +application. + +> **Warning** +> +> Avoid using your root directory, `/`, as the `PATH` for your build context, +> as it causes the build to transfer the entire contents of your hard drive to +> the daemon. +{:.warning} So, in accordance with the build command issued and how build context works, your Dockerfile and python app need to be in the same directory. diff --git a/language/golang/build-images.md b/language/golang/build-images.md index 8638288b8a03..5549098dbedb 100644 --- a/language/golang/build-images.md +++ b/language/golang/build-images.md @@ -15,6 +15,9 @@ redirect_from: is a good starting point, so go (pun intended) check it out. * Some awareness of basic Docker concepts. If unsure, work through the orientation and setup in Get started [Part 1](../../get-started/index.md). +* Basic understanding of the [Dockerfile format](../../build/building/packaging.md#dockerfile). +* Ensure you have [enabled BuildKit](../../build/buildkit/index.md#getting-started) + on your machine. ## Overview @@ -132,8 +135,6 @@ to "dockerizing" it. ## Create a Dockerfile for the application -{% 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/java/build-images.md b/language/java/build-images.md index d60478323618..d031ec8ef355 100644 --- a/language/java/build-images.md +++ b/language/java/build-images.md @@ -10,6 +10,7 @@ description: Learn how to build your first Docker image by writing a Dockerfile * Some awareness of basic Docker concepts. If unsure, work through the orientation and setup in Get started [Part 1](../../get-started/index.md). +* Basic understanding of the [Dockerfile format](../../build/building/packaging.md#dockerfile). * Ensure you have [enabled BuildKit](../../build/buildkit/index.md#getting-started) on your machine. @@ -74,8 +75,6 @@ We will now continue to build and run the application in Docker. ## Create a Dockerfile for Java -{% 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 ce049ebc9e8f..fff467f6c555 100644 --- a/language/nodejs/build-images.md +++ b/language/nodejs/build-images.md @@ -12,6 +12,7 @@ redirect_from: * Some awareness of basic Docker concepts. If unsure, work through the orientation and setup in Get started [Part 1](../../get-started/index.md). +* Basic understanding of the [Dockerfile format](../../build/building/packaging.md#dockerfile). * Ensure you have [enabled BuildKit](../../build/buildkit/index.md#getting-started) on your machine. @@ -94,8 +95,6 @@ We will now continue to build and run the application in Docker. ## Create a Dockerfile for Node.js -{% 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 8931c924de8d..4fffb774c4cf 100644 --- a/language/python/build-images.md +++ b/language/python/build-images.md @@ -10,6 +10,7 @@ description: Learn how to build your first Docker image by writing a Dockerfile * Some awareness of basic Docker concepts. If unsure, work through the orientation and setup in Get started [Part 1](../../get-started/index.md). +* Basic understanding of the [Dockerfile format](../../build/building/packaging.md#dockerfile). * Ensure you have [enabled BuildKit](../../build/buildkit/index.md#getting-started) on your machine. @@ -69,8 +70,6 @@ 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. -{% 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.