Skip to content

Commit 21e1680

Browse files
thaJeztahsfsmithcha
thaJeztah
authored and
sfsmithcha
committed
Merge pull request moby#25709 from thaJeztah/fix-missing-docs-for-binary-remote-context
Add missing docs about binary remote contexts (cherry picked from commit b4abe38) Signed-off-by: Charles Smith <[email protected]>
1 parent 88bd4cb commit 21e1680

8 files changed

Lines changed: 108 additions & 40 deletions

‎docs/reference/api/docker_remote_api_v1.19.md‎

Lines changed: 3 additions & 7 deletions
Original file line numberDiff line numberDiff line change
@@ -1252,13 +1252,9 @@ or being killed.
12521252
ignored if `remote` is specified and points to an individual filename.
12531253
- **t** – A name and optional tag to apply to the image in the `name:tag` format.
12541254
If you omit the `tag` the default `latest` value is assumed.
1255-
- **remote** – A Git repository URI or HTTP/HTTPS context URI. If the
1256-
URI points to a single text file, the file's contents are placed into
1257-
a file called `Dockerfile` and the image is built from that file. If
1258-
the URI points to a tarball, the file is downloaded by the daemon and
1259-
the contents therein used as the context for the build. If the URI
1260-
points to a tarball and the `dockerfile` parameter is also specified,
1261-
there must be a file with the corresponding path inside the tarball.
1255+
- **remote** – A Git repository URI or HTTP/HTTPS URI build source. If the
1256+
URI specifies a filename, the file's contents are placed into a file
1257+
called `Dockerfile`.
12621258
- **q** – Suppress verbose build output.
12631259
- **nocache** – Do not use the cache when building the image.
12641260
- **pull** - Attempt to pull the image even if an older image exists locally.

‎docs/reference/api/docker_remote_api_v1.20.md‎

Lines changed: 7 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -1375,13 +1375,17 @@ or being killed.
13751375

13761376
**Query parameters**:
13771377

1378-
- **dockerfile** - Path within the build context to the Dockerfile. This is
1379-
ignored if `remote` is specified and points to an individual filename.
1378+
- **dockerfile** - Path within the build context to the `Dockerfile`. This is
1379+
ignored if `remote` is specified and points to an external `Dockerfile`.
13801380
- **t** – A name and optional tag to apply to the image in the `name:tag` format.
13811381
If you omit the `tag` the default `latest` value is assumed.
13821382
- **remote** – A Git repository URI or HTTP/HTTPS context URI. If the
13831383
URI points to a single text file, the file's contents are placed into
1384-
a file called `Dockerfile` and the image is built from that file.
1384+
a file called `Dockerfile` and the image is built from that file. If
1385+
the URI points to a tarball, the file is downloaded by the daemon and
1386+
the contents therein used as the context for the build. If the URI
1387+
points to a tarball and the `dockerfile` parameter is also specified,
1388+
there must be a file with the corresponding path inside the tarball.
13851389
- **q** – Suppress verbose build output.
13861390
- **nocache** – Do not use the cache when building the image.
13871391
- **pull** - Attempt to pull the image even if an older image exists locally.

‎docs/reference/api/docker_remote_api_v1.21.md‎

Lines changed: 7 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -1453,14 +1453,18 @@ or being killed.
14531453

14541454
**Query parameters**:
14551455

1456-
- **dockerfile** - Path within the build context to the Dockerfile. This is
1457-
ignored if `remote` is specified and points to an individual filename.
1456+
- **dockerfile** - Path within the build context to the `Dockerfile`. This is
1457+
ignored if `remote` is specified and points to an external `Dockerfile`.
14581458
- **t** – A name and optional tag to apply to the image in the `name:tag` format.
14591459
If you omit the `tag` the default `latest` value is assumed.
14601460
You can provide one or more `t` parameters.
14611461
- **remote** – A Git repository URI or HTTP/HTTPS context URI. If the
14621462
URI points to a single text file, the file's contents are placed into
1463-
a file called `Dockerfile` and the image is built from that file.
1463+
a file called `Dockerfile` and the image is built from that file. If
1464+
the URI points to a tarball, the file is downloaded by the daemon and
1465+
the contents therein used as the context for the build. If the URI
1466+
points to a tarball and the `dockerfile` parameter is also specified,
1467+
there must be a file with the corresponding path inside the tarball.
14641468
- **q** – Suppress verbose build output.
14651469
- **nocache** – Do not use the cache when building the image.
14661470
- **pull** - Attempt to pull the image even if an older image exists locally.

‎docs/reference/api/docker_remote_api_v1.22.md‎

Lines changed: 7 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -1630,14 +1630,18 @@ or being killed.
16301630

16311631
**Query parameters**:
16321632

1633-
- **dockerfile** - Path within the build context to the Dockerfile. This is
1634-
ignored if `remote` is specified and points to an individual filename.
1633+
- **dockerfile** - Path within the build context to the `Dockerfile`. This is
1634+
ignored if `remote` is specified and points to an external `Dockerfile`.
16351635
- **t** – A name and optional tag to apply to the image in the `name:tag` format.
16361636
If you omit the `tag` the default `latest` value is assumed.
16371637
You can provide one or more `t` parameters.
16381638
- **remote** – A Git repository URI or HTTP/HTTPS context URI. If the
16391639
URI points to a single text file, the file's contents are placed into
1640-
a file called `Dockerfile` and the image is built from that file.
1640+
a file called `Dockerfile` and the image is built from that file. If
1641+
the URI points to a tarball, the file is downloaded by the daemon and
1642+
the contents therein used as the context for the build. If the URI
1643+
points to a tarball and the `dockerfile` parameter is also specified,
1644+
there must be a file with the corresponding path inside the tarball.
16411645
- **q** – Suppress verbose build output.
16421646
- **nocache** – Do not use the cache when building the image.
16431647
- **pull** - Attempt to pull the image even if an older image exists locally.

‎docs/reference/api/docker_remote_api_v1.23.md‎

Lines changed: 7 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -1663,14 +1663,18 @@ or being killed.
16631663

16641664
**Query parameters**:
16651665

1666-
- **dockerfile** - Path within the build context to the Dockerfile. This is
1667-
ignored if `remote` is specified and points to an individual filename.
1666+
- **dockerfile** - Path within the build context to the `Dockerfile`. This is
1667+
ignored if `remote` is specified and points to an external `Dockerfile`.
16681668
- **t** – A name and optional tag to apply to the image in the `name:tag` format.
16691669
If you omit the `tag` the default `latest` value is assumed.
16701670
You can provide one or more `t` parameters.
16711671
- **remote** – A Git repository URI or HTTP/HTTPS context URI. If the
16721672
URI points to a single text file, the file's contents are placed into
1673-
a file called `Dockerfile` and the image is built from that file.
1673+
a file called `Dockerfile` and the image is built from that file. If
1674+
the URI points to a tarball, the file is downloaded by the daemon and
1675+
the contents therein used as the context for the build. If the URI
1676+
points to a tarball and the `dockerfile` parameter is also specified,
1677+
there must be a file with the corresponding path inside the tarball.
16741678
- **q** – Suppress verbose build output.
16751679
- **nocache** – Do not use the cache when building the image.
16761680
- **pull** - Attempt to pull the image even if an older image exists locally.

‎docs/reference/api/docker_remote_api_v1.24.md‎

Lines changed: 7 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -1664,14 +1664,18 @@ or being killed.
16641664

16651665
**Query parameters**:
16661666

1667-
- **dockerfile** - Path within the build context to the Dockerfile. This is
1668-
ignored if `remote` is specified and points to an individual filename.
1667+
- **dockerfile** - Path within the build context to the `Dockerfile`. This is
1668+
ignored if `remote` is specified and points to an external `Dockerfile`.
16691669
- **t** – A name and optional tag to apply to the image in the `name:tag` format.
16701670
If you omit the `tag` the default `latest` value is assumed.
16711671
You can provide one or more `t` parameters.
16721672
- **remote** – A Git repository URI or HTTP/HTTPS context URI. If the
16731673
URI points to a single text file, the file's contents are placed into
1674-
a file called `Dockerfile` and the image is built from that file.
1674+
a file called `Dockerfile` and the image is built from that file. If
1675+
the URI points to a tarball, the file is downloaded by the daemon and
1676+
the contents therein used as the context for the build. If the URI
1677+
points to a tarball and the `dockerfile` parameter is also specified,
1678+
there must be a file with the corresponding path inside the tarball.
16751679
- **q** – Suppress verbose build output.
16761680
- **nocache** – Do not use the cache when building the image.
16771681
- **pull** - Attempt to pull the image even if an older image exists locally.

‎docs/reference/api/docker_remote_api_v1.25.md‎

Lines changed: 7 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -1669,14 +1669,18 @@ or being killed.
16691669

16701670
**Query parameters**:
16711671

1672-
- **dockerfile** - Path within the build context to the Dockerfile. This is
1673-
ignored if `remote` is specified and points to an individual filename.
1672+
- **dockerfile** - Path within the build context to the `Dockerfile`. This is
1673+
ignored if `remote` is specified and points to an external `Dockerfile`.
16741674
- **t** – A name and optional tag to apply to the image in the `name:tag` format.
16751675
If you omit the `tag` the default `latest` value is assumed.
16761676
You can provide one or more `t` parameters.
16771677
- **remote** – A Git repository URI or HTTP/HTTPS context URI. If the
16781678
URI points to a single text file, the file's contents are placed into
1679-
a file called `Dockerfile` and the image is built from that file.
1679+
a file called `Dockerfile` and the image is built from that file. If
1680+
the URI points to a tarball, the file is downloaded by the daemon and
1681+
the contents therein used as the context for the build. If the URI
1682+
points to a tarball and the `dockerfile` parameter is also specified,
1683+
there must be a file with the corresponding path inside the tarball.
16801684
- **q** – Suppress verbose build output.
16811685
- **nocache** – Do not use the cache when building the image.
16821686
- **pull** - Attempt to pull the image even if an older image exists locally.

‎docs/reference/commandline/build.md‎

Lines changed: 63 additions & 15 deletions
Original file line numberDiff line numberDiff line change
@@ -49,13 +49,18 @@ to any of the files in the context. For example, your build can use an
4949
[*ADD*](../builder.md#add) instruction to reference a file in the
5050
context.
5151

52-
The `URL` parameter can specify the location of a Git repository; the repository
53-
acts as the build context. The system recursively clones the repository and its
54-
submodules using a `git clone --depth 1 --recursive` command. This command runs
55-
in a temporary directory on your local host. After the command succeeds, the
56-
directory is sent to the Docker daemon as the context. Local clones give you the
57-
ability to access private repositories using local user credentials, VPNs, and
58-
so forth.
52+
The `URL` parameter can refer to three kinds of resources: Git repositories,
53+
pre-packaged tarball contexts and plain text files.
54+
55+
### Git repositories
56+
57+
When the `URL` parameter points to the location of a Git repository, the
58+
repository acts as the build context. The system recursively clones the
59+
repository and its submodules using a `git clone --depth 1 --recursive`
60+
command. This command runs in a temporary directory on your local host. After
61+
the command succeeds, the directory is sent to the Docker daemon as the
62+
context. Local clones give you the ability to access private repositories using
63+
local user credentials, VPN's, and so forth.
5964

6065
Git URLs accept context configuration in their fragment section, separated by a
6166
colon `:`. The first part represents the reference that Git will check out,
@@ -84,9 +89,29 @@ Build Syntax Suffix | Commit Used | Build Context Used
8489
`myrepo.git#mybranch:myfolder` | `refs/heads/mybranch` | `/myfolder`
8590
`myrepo.git#abcdef:myfolder` | `sha1 = abcdef` | `/myfolder`
8691

92+
93+
### Tarball contexts
94+
95+
If you pass an URL to a remote tarball, the URL itself is sent to the daemon:
96+
8797
Instead of specifying a context, you can pass a single Dockerfile in the `URL`
8898
or pipe the file in via `STDIN`. To pipe a Dockerfile from `STDIN`:
8999

100+
```bash
101+
$ docker build http://server/context.tar.gz
102+
103+
The download operation will be performed on the host the Docker daemon is
104+
running on, which is not necessarily the same host from which the build command
105+
is being issued. The Docker daemon will fetch `context.tar.gz` and use it as the
106+
build context. Tarball contexts must be tar archives conforming to the standard
107+
`tar` UNIX format and can be compressed with any one of the 'xz', 'bzip2',
108+
'gzip' or 'identity' (no compression) formats.
109+
110+
### Text files
111+
112+
Instead of specifying a context, you can pass a single `Dockerfile` in the
113+
`URL` or pipe the file in via `STDIN`. To pipe a `Dockerfile` from `STDIN`:
114+
90115
```bash
91116
$ docker build - < Dockerfile
92117
```
@@ -97,16 +122,16 @@ With Powershell on Windows, you can run:
97122
Get-Content Dockerfile | docker build -
98123
```
99124

100-
If you use STDIN or specify a `URL`, the system places the contents into a file
101-
called `Dockerfile`, and any `-f`, `--file` option is ignored. In this
102-
scenario, there is no context.
125+
If you use `STDIN` or specify a `URL` pointing to a plain text file, the system
126+
places the contents into a file called `Dockerfile`, and any `-f`, `--file`
127+
option is ignored. In this scenario, there is no context.
103128

104129
By default the `docker build` command will look for a `Dockerfile` at the root
105130
of the build context. The `-f`, `--file`, option lets you specify the path to
106131
an alternative file to use instead. This is useful in cases where the same set
107132
of files are used for multiple builds. The path must be to a file within the
108-
build context. If a relative path is specified then it must to be relative to
109-
the current directory.
133+
build context. If a relative path is specified then it is interpreted as
134+
relative to the root of the context.
110135

111136
In most cases, it's best to put each Dockerfile in an empty directory. Then,
112137
add to that directory only the files needed for building the Dockerfile. To
@@ -199,9 +224,32 @@ $ docker build github.com/creack/docker-firefox
199224
```
200225
201226
This will clone the GitHub repository and use the cloned repository as context.
202-
The Dockerfile at the root of the repository is used as Dockerfile. Note that
203-
you can specify an arbitrary Git repository by using the `git://` or `git@`
204-
scheme.
227+
The Dockerfile at the root of the repository is used as Dockerfile. You can
228+
specify an arbitrary Git repository by using the `git://` or `git@` scheme.
229+
230+
```bash
231+
$ docker build -f ctx/Dockerfile http://server/ctx.tar.gz
232+
233+
Downloading context: http://server/ctx.tar.gz [===================>] 240 B/240 B
234+
Step 0 : FROM busybox
235+
---> 8c2e06607696
236+
Step 1 : ADD ctx/container.cfg /
237+
---> e7829950cee3
238+
Removing intermediate container b35224abf821
239+
Step 2 : CMD /bin/ls
240+
---> Running in fbc63d321d73
241+
---> 3286931702ad
242+
Removing intermediate container fbc63d321d73
243+
Successfully built 377c409b35e4
244+
```
245+
246+
This sends the URL `http://server/ctx.tar.gz` to the Docker daemon, which
247+
downloads and extracts the referenced tarball. The `-f ctx/Dockerfile`
248+
parameter specifies a path inside `ctx.tar.gz` to the `Dockerfile` that is used
249+
to build the image. Any `ADD` commands in that `Dockerfile` that refer to local
250+
paths must be relative to the root of the contents inside `ctx.tar.gz`. In the
251+
example above, the tarball contains a directory `ctx/`, so the `ADD
252+
ctx/container.cfg /` operation works as expected.
205253
206254
### Build with -
207255

0 commit comments

Comments
 (0)