remove references to 'source repository'
- rewrite intro to Dockerfile reference usage section to remove references to 'source repository' - Closes #14714 - Fixes: #8648 - Updating with Seb's comments Signed-off-by: Mary Anthony <mary@docker.com>
This commit is contained in:
parent
7e3088c43b
commit
b143c05d64
|
@ -10,48 +10,50 @@ parent = "mn_reference"
|
|||
|
||||
# Dockerfile reference
|
||||
|
||||
**Docker can build images automatically** by reading the instructions
|
||||
from a `Dockerfile`. A `Dockerfile` is a text document that contains all
|
||||
the commands you would normally execute manually in order to build a
|
||||
Docker image. By calling `docker build` from your terminal, you can have
|
||||
Docker build your image step by step, executing the instructions
|
||||
successively.
|
||||
Docker can build images automatically by reading the instructions from 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. Using `docker build`
|
||||
users can create an automated build that executes several command-line
|
||||
instructions in succession.
|
||||
|
||||
This page discusses the specifics of all the instructions you can use in your
|
||||
`Dockerfile`. To further help you write a clear, readable, maintainable
|
||||
`Dockerfile`, we've also written a [`Dockerfile` Best Practices
|
||||
guide](/articles/dockerfile_best-practices). Lastly, you can test your
|
||||
Dockerfile knowledge with the [Dockerfile tutorial](/userguide/level1).
|
||||
This page describes the commands you can use in a `Dockerfile`. When you are
|
||||
done reading this page, refer to the [`Dockerfile` Best
|
||||
Practices](/articles/dockerfile_best-practices) for a tip-oriented guide.
|
||||
|
||||
## Usage
|
||||
|
||||
To [*build*](/reference/commandline/build) an image from a source repository,
|
||||
create a description file called `Dockerfile` at the root of your repository.
|
||||
This file will describe the steps to assemble the image.
|
||||
The [`docker build`](/reference/commandline/build/) command builds an image from
|
||||
a `Dockerfile` and a *context*. The build's context is the files at a specified
|
||||
location `PATH` or `URL`. The `PATH` is a directory on your local filesystem.
|
||||
The `URL` is a the location of a Git repository.
|
||||
|
||||
Then call `docker build` with the path of your source repository as the argument
|
||||
(for example, `.`):
|
||||
A context is processed recursively. So, a `PATH` includes any subdirectories and
|
||||
the `URL` includes the repository and its submodules. A simple build command
|
||||
that uses the current directory as context:
|
||||
|
||||
$ docker build .
|
||||
Sending build context to Docker daemon 6.51 MB
|
||||
...
|
||||
|
||||
The path to the source repository defines where to find the *context* of
|
||||
the build. The build is run by the Docker daemon, not by the CLI, so the
|
||||
whole context must be transferred to the daemon. The Docker CLI reports
|
||||
"Sending build context to Docker daemon" when the context is sent to the daemon.
|
||||
The build is run by the Docker daemon, not by the CLI. The first thing a build
|
||||
process does is send the entire context (recursively) to the daemon. In most
|
||||
cases, it's best to start with an empty directory as context and keep your
|
||||
Dockerfile in that directory. Add only the files needed for building the
|
||||
Dockerfile.
|
||||
|
||||
> **Warning**
|
||||
> Avoid using your root directory, `/`, as the root of the source repository. The
|
||||
> `docker build` command will use whatever directory contains the Dockerfile as the build
|
||||
> context (including all of its subdirectories). The build context will be sent to the
|
||||
> Docker daemon before building the image, which means if you use `/` as the source
|
||||
> repository, the entire contents of your hard drive will get sent to the daemon (and
|
||||
> thus to the machine running the daemon). You probably don't want that.
|
||||
>**Warning**: Do not use your root directory, `/`, as the `PATH` as it causes
|
||||
>the build to transfer the entire contents of your hard drive to the Docker
|
||||
>daemon.
|
||||
|
||||
In most cases, it's best to put each Dockerfile in an empty directory. Then,
|
||||
only add the files needed for building the Dockerfile to the directory. To
|
||||
increase the build's performance, you can exclude files and directories by
|
||||
adding a `.dockerignore` file to the directory. For information about how to
|
||||
[create a `.dockerignore` file](#dockerignore-file) on this page.
|
||||
To use a file in the build context, the `Dockerfile` refers to the file with
|
||||
an instruction, for example, a `COPY` instruction. To increase the build's
|
||||
performance, exclude files and directories by adding a `.dockerignore` file to
|
||||
the context directory. For information about how to [create a `.dockerignore`
|
||||
file](#dockerignore-file) see the documentation on this page.
|
||||
|
||||
Traditionally, the `Dockerfile` is called `Dockerfile` and located in the root
|
||||
of the context. You use the `-f` flag with `docker build` to point to a Dockerfile
|
||||
anywhere in your file system.
|
||||
|
||||
You can specify a repository and tag at which to save the new image if
|
||||
the build succeeds:
|
||||
|
|
Loading…
Reference in New Issue