beenull/moby
1
0
Fork 0
Code Issues Pull requests Projects Releases Packages Wiki Activity

remove references to 'source repository'

Browse source 
- 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:
Morgan Bauer 2015-07-17 11:40:56 -07:00 committed by Mary Anthony
parent 7e3088c43b
commit b143c05d64
1 changed files with 39 additions and 37 deletions
Show stats Download patch file Download diff file Expand all files Collapse all files

76
docs/reference/builder.md
View file

@ -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:
@ -166,13 +168,13 @@ as well as:
> variable, even when combined with any of the instructions listed above.
Environment variable substitution will use the same value for each variable
throughout the entire command. In other words, in this example:
throughout the entire command. In other words, in this example:
ENV abc=hello
ENV abc=bye def=$abc
ENV ghi=$abc
will result in `def` having a value of `hello`, not `bye`. However,
will result in `def` having a value of `hello`, not `bye`. However,
`ghi` will have a value of `bye` because it is not part of the same command
that set `abc` to `bye`.
@ -191,7 +193,7 @@ expansion) is done using Go's
You can specify exceptions to exclusion rules. To do this, simply prefix a
pattern with an `!` (exclamation mark) in the same way you would in a
`.gitignore` file. Currently there is no support for regular expressions.
`.gitignore` file. Currently there is no support for regular expressions.
Formats like `[^temp*]` are ignored.
The following is an example `.dockerignore` file:
@ -310,7 +312,7 @@ commands using a base image that does not contain `/bin/sh`.
The cache for `RUN` instructions isn't invalidated automatically during
the next build. The cache for an instruction like
`RUN apt-get dist-upgrade -y` will be reused during the next build. The
`RUN apt-get dist-upgrade -y` will be reused during the next build. The
cache for `RUN` instructions can be invalidated by using the `--no-cache`
flag, for example `docker build --no-cache`.
@ -888,7 +890,7 @@ The `VOLUME` instruction creates a mount point with the specified name
and marks it as holding externally mounted volumes from native host or other
containers. The value can be a JSON array, `VOLUME ["/var/log/"]`, or a plain
string with multiple arguments, such as `VOLUME /var/log` or `VOLUME /var/log
/var/db`. For more information/examples and mounting instructions via the
/var/db`. For more information/examples and mounting instructions via the
Docker client, refer to
[*Share Directories via Volumes*](/userguide/dockervolumes/#mount-a-host-directory-as-a-data-volume)
documentation.