Current versions of the docs generator take this into account, but on
the 20.10 branch, the trailing whitespace can make the YAML generator
switch to use "compact" formatting, which is hard to read, and hard
to review diffs when updating.
Signed-off-by: Sebastiaan van Stijn <github@gone.nl>
Keep frontmatter for docker, dockerd and index markdown files.
Also needs to move cli.md > docker.md before generation and
then move it back because cli.md is needed for yaml generation on docs
website: https://github.com/docker/cli/pull/3924#discussion_r1059986605
Signed-off-by: Kevin Alvarez <crazy-max@users.noreply.github.com>
Signed-off-by: Sebastiaan van Stijn <github@gone.nl>
I think the cli code block misses a backslash to brevent line break when copy/pasting it to a terminal.
I doubt that this is intentional, if it is, feel free to reject the pr.
Signed-off-by: Julian <gitea+julian@ic.thejulian.uk>
Use /bin/sh in the examples, as it's more likely to be present in a
container than bash (some users got confused by this, so using plain
"sh" in the examples could lead to less confusion).
Also added some extra wording around defaults, and how they're inherited
by the exec'd process.
It's definitely not "perfect" yet (lots to do in this document to improve
it), but it's a start :)
Signed-off-by: Sebastiaan van Stijn <github@gone.nl>
Update the example output to not use deprecated storage drivers or
Windows versions.
Also removes the section about `--debug`, because the `docker info` output
depends on the _daemon_ (not the client) to have debug mode enabled.
Signed-off-by: Sebastiaan van Stijn <github@gone.nl>
using latest ubuntu LTS, and alpine for some examples. Also syncing some
wording between the man-pages and online docs.
Signed-off-by: Sebastiaan van Stijn <github@gone.nl>
Some touch-ups in the attach reference and man-page;
- remove uses of old images (ubuntu 14.04)
- adds some more wording about `-i` and `-t` to use the detach sequence.
- use `--filter` instead of `grep` to list the container, to make the
example more portable.
Signed-off-by: Sebastiaan van Stijn <github@gone.nl>
Docker v1.12 is really old, so no need to continue including this
in the docs. Also reformatted a markdown table.
Signed-off-by: Sebastiaan van Stijn <github@gone.nl>
As a stepping-stone towards switching to go modules, we're switching the
versioning scheme to be SemVer(ish) instead of CalVer. Note that this
currently still is `+incompatible` version, as changing to a version > 1
requires the module to be renamed, but changes in that area will arrive
in a future release.
Signed-off-by: Sebastiaan van Stijn <github@gone.nl>
This fix tries to address issues raised in moby/moby#44346.
The max-concurrent-downloads and max-concurrent-uploads limits are applied for the whole engine and not for each pull/push command.
Signed-off-by: Luis Henrique Mulinari <luis.mulinari@gmail.com>
This example was mounting `/dev/zero` as `/dev/nulo` inside the container.
The `nulo` name was intended to be a "made up / custom" name, but various
readers thought it to be a typo for `/dev/null`.
This patch updates the example to use `/dev/foobar` as name, which should
make it more clear that it's a custom name.
Signed-off-by: Sebastiaan van Stijn <github@gone.nl>
Commit 955c1f881a
(v17.12.0) replaced detection of support for multiple lowerdirs (as required by
overlay2) to not depend on the kernel version. The `overlay2.override_kernel_check`
was still used to print a warning that older kernel versions may not have full
support.
After this, e226aea280
(v20.10, but backported to v19.03.7) removed uses of the option altogether.
Signed-off-by: Sebastiaan van Stijn <github@gone.nl>
> Security options with `:` as a separator are deprecated and will be completely unsupported in 17.04, use `=` instead.
Signed-off-by: Felix Geyer <debfx@fobos.de>
While fixing, also updated errors without placeholders to `errors.New()`, and
updated some code to use pkg/errors if it was already in use in the file.
cli/command/config/inspect.go:59:10: ST1005: error strings should not be capitalized (stylecheck)
return fmt.Errorf("Cannot supply extra formatting options to the pretty template")
^
cli/command/node/inspect.go:61:10: ST1005: error strings should not be capitalized (stylecheck)
return fmt.Errorf("Cannot supply extra formatting options to the pretty template")
^
cli/command/secret/inspect.go:57:10: ST1005: error strings should not be capitalized (stylecheck)
return fmt.Errorf("Cannot supply extra formatting options to the pretty template")
^
cli/command/trust/common.go:77:74: ST1005: error strings should not be capitalized (stylecheck)
return []trustTagRow{}, []client.RoleWithSignatures{}, []data.Role{}, fmt.Errorf("No signatures or cannot access %s", remote)
^
cli/command/trust/common.go:85:73: ST1005: error strings should not be capitalized (stylecheck)
return []trustTagRow{}, []client.RoleWithSignatures{}, []data.Role{}, fmt.Errorf("No signers for %s", remote)
^
cli/command/trust/sign.go:137:10: ST1005: error strings should not be capitalized (stylecheck)
return fmt.Errorf("No tag specified for %s", imgRefAndAuth.Name())
^
cli/command/trust/sign.go:151:19: ST1005: error strings should not be capitalized (stylecheck)
return *target, fmt.Errorf("No tag specified")
^
cli/command/trust/signer_add.go:77:10: ST1005: error strings should not be capitalized (stylecheck)
return fmt.Errorf("Failed to add signer to: %s", strings.Join(errRepos, ", "))
^
cli/command/trust/signer_remove.go:52:10: ST1005: error strings should not be capitalized (stylecheck)
return fmt.Errorf("Error removing signer from: %s", strings.Join(errRepos, ", "))
^
cli/command/trust/signer_remove.go:67:17: ST1005: error strings should not be capitalized (stylecheck)
return false, fmt.Errorf("All signed tags are currently revoked, use docker trust sign to fix")
^
cli/command/trust/signer_remove.go:108:17: ST1005: error strings should not be capitalized (stylecheck)
return false, fmt.Errorf("No signer %s for repository %s", signerName, repoName)
^
opts/hosts.go:89:14: ST1005: error strings should not be capitalized (stylecheck)
return "", fmt.Errorf("Invalid bind address format: %s", addr)
^
opts/hosts.go💯14: ST1005: error strings should not be capitalized (stylecheck)
return "", fmt.Errorf("Invalid proto, expected %s: %s", proto, addr)
^
opts/hosts.go:119:14: ST1005: error strings should not be capitalized (stylecheck)
return "", fmt.Errorf("Invalid proto, expected tcp: %s", tryAddr)
^
opts/hosts.go:144:14: ST1005: error strings should not be capitalized (stylecheck)
return "", fmt.Errorf("Invalid bind address format: %s", tryAddr)
^
opts/hosts.go:155:14: ST1005: error strings should not be capitalized (stylecheck)
return "", fmt.Errorf("Invalid bind address format: %s", tryAddr)
^
Signed-off-by: Sebastiaan van Stijn <github@gone.nl>
These options were soft-deprecated in Docker 17.05, and at the time
considered to not be removed. However, with the move towards containerd
snapshotters, having these options around adds additional complexity to
handle fallbacks for deprecated (and hidden) flags, so completing the
deprecation.
Signed-off-by: Sebastiaan van Stijn <github@gone.nl>
Cobra allows for aliases to be defined for a command, but only allows these
to be defined at the same level (for example, `docker image ls` as alias for
`docker image list`). Our CLI has some commands that are available both as a
top-level shorthand as well as `docker <object> <verb>` subcommands. For example,
`docker ps` is a shorthand for `docker container ps` / `docker container ls`.
This patch introduces a custom "aliases" annotation that can be used to print
all available aliases for a command. While this requires these aliases to be
defined manually, in practice the list of aliases rarely changes, so maintenance
should be minimal.
As a convention, we could consider the first command in this list to be the
canonical command, so that we can use this information to add redirects in
our documentation in future.
Before this patch:
docker images --help
Usage: docker images [OPTIONS] [REPOSITORY[:TAG]]
List images
Options:
-a, --all Show all images (default hides intermediate images)
...
With this patch:
docker images --help
Usage: docker images [OPTIONS] [REPOSITORY[:TAG]]
List images
Aliases:
docker image ls, docker image list, docker images
Options:
-a, --all Show all images (default hides intermediate images)
...
Signed-off-by: Sebastiaan van Stijn <github@gone.nl>
The `DEBIAN_FRONTEND` environment variable is used to control the interface by which debconf questions are presented to the user (see [`man 7 debconf`][1]). In `DEBIAN_FRONTEND=noninteractive apt-get update && apt-get install -y`, the `DEBIAN_FRONTEND` environment variable is only set for the `apt-get update` command which does not ask debconf questions, and will not affect the `apt-get install` command where these questions are actually asked. It should be the other way around.
[1]: https://manpages.debian.org/debconf.7.html
Signed-off-by: Murukesh Mohanan <murukesh.mohanan@gmail.com>
Move the "default output" section into the description, and
describe the section that can be found in the output.
Signed-off-by: Sebastiaan van Stijn <github@gone.nl>
Wording and documentation still need to be updated, but will do
so in a follow-up.
Also removing the default "10 seconds" from the timeout flags, as
this default is not actually used, and may not match the actual
default (which is defined on the daemon side).
Signed-off-by: Sebastiaan van Stijn <github@gone.nl>
Getting the client API version is non-intuitive.
Other keys follow the json example or the version output, however `'{{.Client.ApiVersion}}'` does not work, nor does `'{{.Client.APIversion}}'`
Signed-off-by: Gabriel Gore <gabgore@cisco.com>
Signed-off-by: Sebastiaan van Stijn <github@gone.nl>
The code is similar to that used by the volume rm subcommand, however,
one difference I noticed was VolumeRemove takes the force flag/option
was a parameter. This isn't the case for NetworkRemove.
To get NetworkRemove to take a similar parameter, this would require
modifying the Docker daemon. For now this isn't a route I wish to take
when the code can be arrange to mimic the same behavior.
Co-authored-by: Sebastiaan van Stijn <github@gone.nl>
Signed-off-by: Conner Crosby <conner@cavcrosby.tech>
This groups all swarm-related subcommands to their own section in the --help
output, to make it clearer which commands require swarm to be enabled
With this change:
Usage: docker [OPTIONS] COMMAND
A self-sufficient runtime for containers
Options:
--config string Location of client config files (default "/Users/sebastiaan/.docker")
-c, --context string Name of the context to use to connect to the daemon (overrides DOCKER_HOST env var and default context set with "docker context use")
-D, --debug Enable debug mode
-H, --host list Daemon socket(s) to connect to
-l, --log-level string Set the logging level ("debug"|"info"|"warn"|"error"|"fatal") (default "info")
--tls Use TLS; implied by --tlsverify
--tlscacert string Trust certs signed only by this CA (default "/Users/sebastiaan/.docker/ca.pem")
--tlscert string Path to TLS certificate file (default "/Users/sebastiaan/.docker/cert.pem")
--tlskey string Path to TLS key file (default "/Users/sebastiaan/.docker/key.pem")
--tlsverify Use TLS and verify the remote
-v, --version Print version information and quit
Management Commands:
builder Manage builds
buildx* Docker Buildx (Docker Inc., v0.8.1)
checkpoint Manage checkpoints
completion Generate the autocompletion script for the specified shell
compose* Docker Compose (Docker Inc., v2.3.3)
container Manage containers
context Manage contexts
image Manage images
manifest Manage Docker image manifests and manifest lists
network Manage networks
plugin Manage plugins
scan* Docker Scan (Docker Inc., v0.17.0)
system Manage Docker
trust Manage trust on Docker images
volume Manage volumes
Orchestration Commands:
config Manage Swarm configs
node Manage Swarm nodes
secret Manage Swarm secrets
service Manage Swarm services
stack Manage Swarm stacks
swarm Manage Swarm
Commands:
attach Attach local standard input, output, and error streams to a running container
build Build an image from a Dockerfile
commit Create a new image from a container's changes
cp Copy files/folders between a container and the local filesystem
create Create a new container
diff Inspect changes to files or directories on a container's filesystem
events Get real time events from the server
exec Run a command in a running container
export Export a container's filesystem as a tar archive
history Show the history of an image
images List images
import Import the contents from a tarball to create a filesystem image
info Display system-wide information
inspect Return low-level information on Docker objects
kill Kill one or more running containers
load Load an image from a tar archive or STDIN
login Log in to a Docker registry
logout Log out from a Docker registry
logs Fetch the logs of a container
pause Pause all processes within one or more containers
port List port mappings or a specific mapping for the container
ps List containers
pull Pull an image or a repository from a registry
push Push an image or a repository to a registry
rename Rename a container
restart Restart one or more containers
rm Remove one or more containers
rmi Remove one or more images
run Run a command in a new container
save Save one or more images to a tar archive (streamed to STDOUT by default)
search Search the Docker Hub for images
start Start one or more stopped containers
stats Display a live stream of container(s) resource usage statistics
stop Stop one or more running containers
tag Create a tag TARGET_IMAGE that refers to SOURCE_IMAGE
top Display the running processes of a container
unpause Unpause all processes within one or more containers
update Update configuration of one or more containers
version Show the Docker version information
wait Block until one or more containers stop, then print their exit codes
Run 'docker COMMAND --help' for more information on a command.
To get more help with docker, check out our guides at https://docs.docker.com/go/guides/
Signed-off-by: Sebastiaan van Stijn <github@gone.nl>
Configuration (enabling/disabling) of Experimental client features
was deprecated in Docker 19.03, and removed in 20.10. Experimental
CLI features are now always enabled. In Docker 20.10, the Experimental
field in `docker version` was kept (but always true).
This patch removes the field from the output (both "pretty" output
and the JSON struct).
Signed-off-by: Sebastiaan van Stijn <github@gone.nl>
Make use of existing modules and functions in order to output the merged configs.
Added skip interpolation flag of variables, so that you can pipe the output back to stack deploy without much hassle.
Signed-off-by: Stoica-Marcu Floris-Andrei <floris.sm@gmail.com>
Signed-off-by: Sebastiaan van Stijn <github@gone.nl>
My IDE's linter kept complaining:
> For compatibility reasons all table rows should have borders (pipe
> symbols) at the start and at the end.
Signed-off-by: Sebastiaan van Stijn <github@gone.nl>
The `~/.dockercfg` file was replaced by `~/.docker/config.json` in 2015
(github.com/docker/docker/commit/18c9b6c6455f116ae59cde8544413b3d7d294a5e),
but the CLI still falls back to checking if this file exists if no current
(`~/.docker/config.json`) file was found.
Given that no version of the CLI since Docker v1.7.0 has created this file,
and if such a file exists, it means someone hasn't re-authenticated for
5 years, it's probably safe to remove this fallback.
Signed-off-by: Sebastiaan van Stijn <github@gone.nl>
Remove "Docker" from registry, as the registry specification is no
longer docker-specific, but part of the OCI distribution spec.
Also removed "Register" from one of the docs pages, as the login
command hasn't supported creating a new acccount on Docker Hub for
a long time.
I'm wondering if we should be more explicit about what log in / out
does (effectively; authenticate, and on success store the credentials
or token, and on log out; remove credentials/token).
Signed-off-by: Sebastiaan van Stijn <github@gone.nl>
This was introduced in 41a5e0e4df, and
having the trailing whitespace causes the yamldocs generator to
switch to "compact" formatting, which makes that yaml hard to read.
Signed-off-by: Sebastiaan van Stijn <github@gone.nl>
This will generate "details_url" for options, so that the options
table on the pages at docs.docker.com link to the section describing
the option.
Signed-off-by: Sebastiaan van Stijn <github@gone.nl>
With this, the sections are linked from the "options" table when
producing the documentation on docs.docker.com
Signed-off-by: Sebastiaan van Stijn <github@gone.nl>
The daemon (and registry) already have a default limit. This patch
removes the default from the client side, to not duplicate setting
these defaults.
Signed-off-by: Sebastiaan van Stijn <github@gone.nl>
With this change all `inspect` commands will output a compact JSON
representation of the elements, the default format (indented JSON) stays the
same.
Signed-off-by: Djordje Lukic <djordje.lukic@docker.com>
Signed-off-by: Sebastiaan van Stijn <github@gone.nl>
This has now been implemented in buildkit#2116, so this note can
be removed (once integrated into Docker).
Signed-off-by: Sebastiaan van Stijn <github@gone.nl>
Support for LCOW has been removed from the daemon, so removing the
corresponding daemon configuration options.
Signed-off-by: Sebastiaan van Stijn <github@gone.nl>
The `docker create` command shares most (all) of its options with `docker run`,
which uses `docker create` under the hood. The `docker create` reference docs
already referred users to the `docker run` sections for details, but some
flags were only documented on the `docker create` page.
This patch:
- moves those flags from the `docker create` to the `docker run` page
- does some minor rephrasing and touch-ups.
Signed-off-by: Sebastiaan van Stijn <github@gone.nl>
These options were added in 22cd418967,
but did not update the documentation.
Signed-off-by: Chee Hau Lim <cheehau.lim@mobimeo.com>
Signed-off-by: Sebastiaan van Stijn <github@gone.nl>
Explicitly mention flags and environment variables that were removed, to
make the deprecation more discoverable.
Signed-off-by: Sebastiaan van Stijn <github@gone.nl>
Remove mentions of which options are supported by Kubernetes.
Note that there's some filters remaining that were marked as "not supported
by swarm": those filters need to be checked if this is accurate (and if so,
those filters must be removed).
Signed-off-by: Sebastiaan van Stijn <github@gone.nl>
Removes the flags that have been deprecated or removed;
- --default-stack-orchestrator
- --kubernetes
- --kubeconfig
- --namespace
- --orchestrator
Signed-off-by: Sebastiaan van Stijn <github@gone.nl>
I didn't see where in the page that `--privileged` mode adds all capabilities.
I think this page once did contain that information. I got it from a Stack Overflow answer that seems to have copied from an earlier version of this same document.
> Full container capabilities (--privileged)
>
> The --privileged flag gives all capabilities to the container, and it also lifts all the limitations enforced by the device cgroup controller. In other words, the container can then do almost everything that the host can do. This flag exists to allow special use-cases, like running Docker within Docker.
https://stackoverflow.com/a/36441605/111424
Signed-off-by: Iain Samuel McLean Elder <iain@isme.es>
- expand a bit on what's happening
- clarify start of deprecation of the classic builder
- show examples of error and warning
Signed-off-by: Sebastiaan van Stijn <github@gone.nl>
> Legacy PEM encryption as specified in RFC 1423 is insecure by design. Since
> it does not authenticate the ciphertext, it is vulnerable to padding oracle
> attacks that can let an attacker recover the plaintext
From https://go-review.googlesource.com/c/go/+/264159
> It's unfortunate that we don't implement PKCS#8 encryption so we can't
> recommend an alternative but PEM encryption is so broken that it's worth
> deprecating outright.
This feature allowed using an encrypted private key with a supplied password,
but did not provide additional security as the encryption is known to be broken,
and the key is sitting next to the password in the filesystem. Users are recommended
to decrypt the private key, and store it un-encrypted to continue using it.
Signed-off-by: Sebastiaan van Stijn <github@gone.nl>
Change the order of received/written and sent/read in NET I/O and BLOCK I/O description reflect the order in I/O (Input/Output).
From example above:
CONTAINER NAME: awesome_brattain
BLOCK I/O: 147kB / 0B
awesome_brattain has written 147kB and read 0B
Signed-off-by: Tomas Bäckman <larstomas@gmail.com>
Ubuntu version references were a mixture of 14.04 (in descriptions) and 20.04 (in example code). Updated description references to 20.04 to match example code.
Signed-off-by: Mike Dalton <mikedalton@github.com>
Commit 9bd3a7c029
(docker 17.04 and up) added a maximum timeout of 1 minute to the
restart timeout.
This patch updates the documentation to match the current behavior.
Signed-off-by: Sebastiaan van Stijn <github@gone.nl>
The DefaultStopSignal const has been deprecated, because the daemon already
handles a default value. The current code did not actually send the default
value unless the flag was set, which also made the flag description incorrect,
because in that case, the _daemon's_ default would be used, which could
potentially be different as was specified here.
This patch removes the default value from the flag, leaving it to the daemon
to set a default.
Signed-off-by: Sebastiaan van Stijn <github@gone.nl>
The /go/ redirects are now defined in the docs repository, so the one
we defined here can be removed.
Also adds a missing redirect for an old URL to the main CLI page.
Signed-off-by: Sebastiaan van Stijn <github@gone.nl>
This replaces the use of bash where suitable, to allow easier copy/pasting
of shell examples without copying the prompt or process output.
Signed-off-by: Sebastiaan van Stijn <github@gone.nl>
- make sure the target directory is created if missing
- add support for custom ID's in headings through `<a>` tags (e.g.
`<a name=heading2></a>`). This allows use of custom anchors that
work both on GitHub (GFM doesn't support extended MarkDown), and
in Jekyll (which does).
- add code to cleanup markdown for use in our docs:
- remove absolute URLs to https://docs.docker.com
- remove tabs in MarkDown, and convert them to 4 spaces. This
prevents the YAML conversion from switching between "short"
and "long" syntax. Tabs in code examples also don't always
work well, so using spaces doesn't hurt for that.
- refactor some code for readability, and to be less "hacky" (still
lots to be improved though)
Signed-off-by: Sebastiaan van Stijn <github@gone.nl>
> Legacy PEM encryption as specified in RFC 1423 is insecure by design. Since
> it does not authenticate the ciphertext, it is vulnerable to padding oracle
> attacks that can let an attacker recover the plaintext
From https://go-review.googlesource.com/c/go/+/264159
> It's unfortunate that we don't implement PKCS#8 encryption so we can't
> recommend an alternative but PEM encryption is so broken that it's worth
> deprecating outright.
Signed-off-by: Sebastiaan van Stijn <github@gone.nl>
Support for ALL_PROXY as default build-arg was added recently in
buildkit and the classic builder.
This patch adds the `ALL_PROXY` environment variable to the list of
configurable proxy variables, and updates the documentation.
Signed-off-by: Sebastiaan van Stijn <github@gone.nl>
This link worked on GitHub, but was broken on docs.docker.com, so
replacing with a regular link directly to the docs instead.
Signed-off-by: Sebastiaan van Stijn <github@gone.nl>
Jekyll doesn't work well with markdown links that are wrapped, so changing
the link to be on a single line.
While at it, also added/changed some code-hints.
Signed-off-by: Sebastiaan van Stijn <github@gone.nl>
More improvements can be made, but this makes a start on cleaning up
this page:
- Reorganise configuration file options into sections
- Use tables for related options to make them easier to find
- Add warning about the config file's possibility to contain sensitive information
- Some MarkDown touch-ups (use "console" code-hint to assist copy/paste)
Signed-off-by: Sebastiaan van Stijn <github@gone.nl>
This is mostly a copy of the equivalent `docker secret` commands,
which uses the same mechanisms behind the hood (hence, are 90% the
same).
We can make further refinements to these docs, but this gives us
a starting point.
Adding these documents, because there were some links pointing to
these pages in the docs, but there was no markdown file to link to
on GitHub.
Signed-off-by: Sebastiaan van Stijn <github@gone.nl>
- rename "experimental" to "labs"
- rephrase recommendation for picking a version
- clarify that the "labs" channel provides a superset of the "stable" channel.
- remove "External implementation features" section, because it overlapped
with the "syntax" section.
- removed `:latest` from the "stable" channel (generally not recommended)
Signed-off-by: Sebastiaan van Stijn <github@gone.nl>
- update some examples to show the BuildKit output
- remove some wording about "images" being used for the build cache
- add a link to the `--cache-from` section
- added a link to "scanning your image with `docker scan`"
- updated link to "push your image"
Signed-off-by: Sebastiaan van Stijn <github@gone.nl>
- use "console" for code-hints, to make process output distinguishable
from the commands that are executed
- use a consistent prompt for powershell examples
- minor changes in wording around "build context" to reduce confusion
with `docker context`
Signed-off-by: Sebastiaan van Stijn <github@gone.nl>
These options are available in Docker 20.10 and up, but were
previously only available in Docker EE, and not documented.
Signed-off-by: Sebastiaan van Stijn <github@gone.nl>
Updates the stop.md doc to mention that the stop signal can be changed, either with the Dockerfile or via `docker run --stop-signal`. This is a real gotcha if you're not familiar with this feature and build a container that extends a container that uses `STOPSIGNAL`.
Signed-off-by: Christopher Vermilion <christopher.vermilion@gmail.com>
recommend using `docker container prune`, but show an example on
how to combine commands with a bit more context and warnings
about portability/compatibility.
Thanks to Charlie Arehart to do the initial work on this.
Signed-off-by: Sebastiaan van Stijn <github@gone.nl>
Some new drivers were added to the "docker run" section to make the documentation more up to date.
Signed-off-by: d.alvarez <david.alvarez@flyeralarm.com>
These options were deprecated and removed in the Linux kernel v5.0 and up in;
- f382fb0bce
- fb5772cbfe
- 23aa16489c
Signed-off-by: Sebastiaan van Stijn <github@gone.nl>
Docker Engine v20.10 and up includes optimizations to verify if images in the
local image cache need updating before pulling, preventing the Docker Engine
from making unnecessary API requests. These optimizations require the container
image registry to conform to the Open Container Initiative Distribution Specification
(https://github.com/opencontainers/distribution-spec).
While most registries conform to the specification, we encountered some registries
to be non-compliant, resulting in `docker pull` to fail.
As a temporary solution, Docker Engine v20.10 includes a fallback mechanism to
allow `docker pull` to be functional when using a non-compliant registry. A
warning message is printed in this situation:
WARNING Failed to pull manifest by the resolved digest. This registry does not
appear to conform to the distribution registry specification; falling back to
pull by tag. This fallback is DEPRECATED, and will be removed in a future
release.
The fallback is added to allow users to either migrate their images to a compliant
registry, or for these registries to become compliant.
Note that this fallback only addresses failures on `docker pull`. Other commands,
such as `docker stack deploy`, or pulling images with `containerd` will continue
to fail.
Given that other functionality is still broken with these registries, we consider
this fallback a _temporary_ solution, and will remove the fallback in an upcoming
major release.
Signed-off-by: Sebastiaan van Stijn <github@gone.nl>
Looks like the YAML conversion doesn't like lines starting with `[`, and
causing it to use the "compact" formatting in the generated YAML.
This patch un-wraps these lines to prevent this.
Signed-off-by: Sebastiaan van Stijn <github@gone.nl>
To create this, I ran every JSON document through `jq -S` (which sorts the keys and consistently pretty-prints the result in a format which matches the majority of documents in this file).
Signed-off-by: Tianon Gravi <admwiggin@gmail.com>
Docker v17.07 introduced an experimental `--stream` flag on `docker build` which
allowed the build-context to be incrementally sent to the daemon, instead of
unconditionally sending the whole build-context.
This functionality has been reimplemented as part of BuildKit, which uses streaming
by default and the `--stream` option will be ignored when using the classic builder,
printing a deprecation warning instead.
Users that want to use this feature are encouraged to enable BuildKit by setting
the `DOCKER_BUILDKIT=1` environment variable or through the daemon or CLI configuration
files.
Signed-off-by: Sebastiaan van Stijn <github@gone.nl>
The experimental feature to run Linux containers on Windows (LCOW) was introduced
as a technical preview in Docker 17.09. While many enhancements were made after
its introduction, the feature never reached completeness, and development has
now stopped in favor of running docker natively on Linux in WSL2.
Developers that need to run Linux workloads on a Windows host are encouraged
to use Docker Desktop with WSL2 instead.
Signed-off-by: Sebastiaan van Stijn <github@gone.nl>
The CLI disabled experimental features by default, requiring users
to set a configuration option to enable them.
Disabling experimental features was a request from Enterprise users
that did not want experimental features to be accessible.
We are changing this policy, and now enable experimental features
by default. Experimental features may still change and/or removed,
and will be highlighted in the documentation and "usage" output.
For example, the `docker manifest inspect --help` output now shows:
EXPERIMENTAL:
docker manifest inspect is an experimental feature.
Experimental features provide early access to product functionality. These features
may change between releases without warning or can be removed entirely from a future
release. Learn more about experimental features: https://docs.docker.com/go/experimental/
Signed-off-by: Sebastiaan van Stijn <github@gone.nl>
Some deprecations are ammended during a major (YY.MM) release, to
inform users as early as possible about deprecations. Removing the
minor version from this overview clarifies that features are
marked deprecated during which major release's lifecycle.
Signed-off-by: Sebastiaan van Stijn <github@gone.nl>
If a file contains trailing whitespace, the YAML generator uses a
compact format, which is hard to read.
Signed-off-by: Sebastiaan van Stijn <github@gone.nl>
The Dockerfile `ENV` instruction allows values to be set using either `ENV name=value`
or `ENV name value`. The latter (`ENV name value`) form can be ambiguous, for example,
the following defines a single env-variable (`ONE`) with value `"TWO= THREE=world"`,
but may have intended to be setting three env-vars:
ENV ONE TWO= THREE=world
This format also does not allow setting multiple environment-variables in a single
`ENV` line in the Dockerfile.
Use of the `ENV name value` syntax is discouraged, and may be removed in a future
release. Users are encouraged to update their Dockerfiles to use the `ENV name=value`
syntax, for example:
ENV ONE="" TWO="" THREE="world"
Signed-off-by: Sebastiaan van Stijn <github@gone.nl>
The `ENV key value` form can be ambiguous, for example, the following defines
a single env-variable (`ONE`) with value `"TWO= THREE=world"`:
ENV ONE TWO= THREE=world
While we cannot deprecate/remove that syntax (as it would break existing
Dockerfiles), we should reduce exposure of the format in our examples.
Signed-off-by: Sebastiaan van Stijn <github@gone.nl>
When creating and updating services, we need to avoid unneeded service churn.
The interaction of separate lists to "add" and "drop" capabilities, a special
("ALL") capability, as well as a "relaxed" format for accepted capabilities
(case-insensitive, `CAP_` prefix optional) make this rather involved.
This patch updates how we handle `--cap-add` / `--cap-drop` when _creating_ as
well as _updating_, with the following rules/assumptions applied:
- both existing (service spec) and new (values passed through flags or in
the compose-file) are normalized and de-duplicated before use.
- the special "ALL" capability is equivalent to "all capabilities" and taken
into account when normalizing capabilities. Combining "ALL" capabilities
and other capabilities is therefore equivalent to just specifying "ALL".
- adding capabilities takes precedence over dropping, which means that if
a capability is both set to be "dropped" and to be "added", it is removed
from the list to "drop".
- the final lists should be sorted and normalized to reduce service churn
- no validation of capabilities is handled by the client. Validation is
delegated to the daemon/server.
When deploying a service using a docker-compose file, the docker-compose file
is *mostly* handled as being "declarative". However, many of the issues outlined
above also apply to compose-files, so similar handling is applied to compose
files as well to prevent service churn.
Signed-off-by: Sebastiaan van Stijn <github@gone.nl>
The docker CLI up until v1.7.0 used the `~/.dockercfg` file to store credentials
after authenticating to a registry (`docker login`). Docker v1.7.0 replaced this
file with a new CLI configuration file, located in `~/.docker/config.json`. When
implementing the new configuration file, the old file (and file-format) was kept
as a fall-back, to assist existing users with migrating to the new file.
Given that the old file format encourages insecure storage of credentials
(credentials are stored unencrypted), and that no version of the CLI since
Docker v1.7.0 has created this file, the file is marked deprecated, and support
for this file will be removed in a future release.
Signed-off-by: Sebastiaan van Stijn <github@gone.nl>
The output format was changed to combine tag and name in a single
column, but this change was never reflected in the docs.
Signed-off-by: Sebastiaan van Stijn <github@gone.nl>
This reflects a Moby change to add documentation around
disabling a new feature -- to use pgzip to decompress
layers, rather than the built-in go gzip.
Signed-off-by: Sargun Dhillon <sargun@sargun.me>
Signed-off-by: Sebastiaan van Stijn <github@gone.nl>
This creates a new section of environment variables in the CLI docs
which documents environment variables that can both be used on dockerd
and on docker cli.
In addition, it moves some of the environment variable documentation
from the docker cli documentation to the dockerd documentation, as
these environment variables are dockerd-specific.
Signed-off-by: Sargun Dhillon <sargun@sargun.me>
Signed-off-by: Sebastiaan van Stijn <github@gone.nl>
The Engine API docs are not available in this GitHub repository,
so linking to the docs.docker.com website instead.
Signed-off-by: Sebastiaan van Stijn <github@gone.nl>
- replace the "none" code-hint with "console"
- some changes in the "experimental" instructions
- reformat some notes
- reformat / re-indent JSON output to use 2 spaces (for consistency)
- split JSON outputs to separate code-block so that it can be highlighted
Signed-off-by: Sebastiaan van Stijn <github@gone.nl>
This adds the currently selected "docker context" to the output
of "docker version", which allows users to see which context
is selected to produce the version output, and can be used (for
example), to set the prompt to the currently selected context:
(in `~/.bashrc`):
```bash
function docker_context_prompt() {
PS1="context: $(docker version --format='{{.Client.Context}}')> "
}
PROMPT_COMMAND=docker_context_prompt
```
After reloading the `~/.bashrc`, the prompt now shows the currently selected
`docker context`:
```bash
$ source ~/.bashrc
context: default> docker context create --docker host=unix:///var/run/docker.sock my-context
my-context
Successfully created context "my-context"
context: default> docker context use my-context
my-context
Current context is now "my-context"
context: my-context> docker context use default
default
Current context is now "default"
context: default>
```
Signed-off-by: Sebastiaan van Stijn <github@gone.nl>
Using `/var/run/docker.sock` as docker host is invalid, and causes
an error, so adding `unix://` to it.
In addition, we document the name of the context to go after the
options, so change the order in the examples.
Signed-off-by: Sebastiaan van Stijn <github@gone.nl>
Bjorn Neergaard
craig-osterhout
Ali Rostami
Yucheng Wu
CrazyMax
Sebastiaan van Stijn
Paweł Gronowski
Melroy van den Berg
Julian
Sam Thibault
Sebastiaan van Stijn
Mathieu Rollet
David Karlsson
Djordje Lukic
Luis Henrique Mulinari
Bishal Das
Felix Geyer
Gio d'Amelio
Alberto Roura
Ben Bodenmiller
Murukesh Mohanan
Phong Tran
Gabriel
Harald Albers
Conner Crosby
Nicolas De Loof
Stoica-Marcu Floris-Andrei
Spring
fezzik1620
Stefan Scherer
Silvin Lubecki
Mozi
Gleb Stsenov
Chee Hau Lim
Iain Samuel McLean Elder
Leonid Skorospelov
Zeel B Patel
Sandro
Pieter E Smit
Andres G. Aragoneses
jlecordier
Tomas Bäckman
Mike Dalton
Peter Dave Hello
Dmitriy Fishman
takeshi.koenuma
Brian Goff
Pawel
Silvin Lubecki
Gsealy
Brad Baker
Ivan Grund
Mathieu Champlon
Takuya Noguchi
Anca Iordache
Govind Rai
Metal
Erik Humphrey
Tianon Gravi
Chris Vermilion
OKA Naoya
Jon Zeolla
Busindre
DongGeon Lee
Tibor Vass
rochfeu
Andres Leon Rangel
Benjamin Böhmke
Kyle
Eric Engestrom
Charlotte Mach
Albin Kerouanton
horpto
eyherabh
Tonis Tiigi
Akihiro Suda
Brian Wieder
dito
Saswat Bhattacharya
Sargun Dhillon
Justin Cormack
Simon Heimberg
devisions